Node-level `mode: read` on an exec node is silently overridden to write-mode at compile (no warning)

[pawellisowski]

Summary

An author-declared node-level mode: read on a host exec node is silently ignored by the compiler. aware app compile overrides it to mode: write and stamps the note "agent installed but command exec not found; defaulting to write-mode for safety" — with no error or warning that the author's explicit declaration was discarded.

app-spec.md documents mode: read as a node-level field (the sheet.list example under the lock-contract section declares mode: read), so authoring it is the documented, intended way to assert a node's read/write intent. For exec — whose read/write mode the compiler cannot infer (it runs arbitrary host code) — the author's explicit mode: read is exactly the signal that should resolve the ambiguity, but it is dropped.

Repro (aware 0.46.0, win-x64)

A read-only tekla/exec node that declares mode: read:

app:           exec-mode-repro
version:       0.1.0
display-name:  exec mode repro
description: |
  A read-only exec node that declares mode: read; the compiler overrides it to write.
exposes-as-agent: false
requires:
  - tekla@0.1.x
layout: linear
nodes:
  - id: probe
    agent: tekla
    command: exec
    mode: read
    config:
      version: "2025.0"
      code: |
        return new { ok = true };
connections: []

$ aware app install ./exec-mode-repro
$ aware app compile exec-mode-repro     # run from ~/.aware/apps
✓ compiled …

Inspect the produced .lock:

nodes:
- id: probe
  kind: agent
  agent: tekla
  command: exec
  mode: write          # ← author declared mode: read; silently overridden
  ...
  notes:
  - agent tekla installed but command exec not found; defaulting to write-mode for safety

Observed

• Author declares mode: read; lock shows mode: write.
• No error/warning that the declaration was ignored. The only signal is the generic "defaulting … for safety" note, which reads as "couldn't determine" rather than "your explicit read declaration was discarded".

Expected (one of)

1. Honor it — an explicit node-level mode: read resolves the otherwise-unknowable exec mode, and the lock records mode: read (no defaulting note). This lets read-only exec apps avoid a misleading write-mode label and a spurious safety: requirement. (preferred)
2. Reject/warn — if mode is not author-settable on exec, the compiler should say so (e.g. E_APP_EXEC_MODE_UNSETTABLE) instead of silently overriding a documented field.

Silently overriding a documented authoring field is the footgun.

Impact

Any read-only host-exec app (e.g. a BOM/report builder that only reads the model and returns HTML inline) is mislabeled write-mode on every node, and — if the v0.11 safety contract's "refuse to install a write-mode node missing safety:" gate were enforced for exec — would be forced to declare bogus safety: blocks for operations that write nothing.

Related: #160 / #161 (recent validate/compile gating around inline kinds and planned agents) — same compile/lock-mode surface.

[pawellisowski]

Reopening — still reproduces on aware 0.46.0 (win-x64). An author-declared node-level `mode: read` on a host `exec` node is still overridden to `mode: write` at compile, with the note "command exec not found; defaulting to write-mode for safety."

Real-world impact: a 3-node read-only Tekla BOM app (`tekla-bom-by-phase`: phase-input / bom / viewer, all `exec` + `mode: read`) produces one such note per node — 3 notes on a workflow that does no writes. The downstream consumer (floless.app, the prompt-native front door) already trusts the author's `mode: read` and has to rephrase the note for users; the lock itself still records `write`.

Preferred fix remains option 1: honor an explicit node-level `mode: read` on `exec`, record `mode: read` in the `.lock`, and suppress the defaulting note.

One diagnostic to check first: the "command exec not found" wording suggests the tekla agent manifest may not declare an `exec` command, so the compiler can't resolve it and falls back to write regardless of the author annotation. So the fix may be (a) honor author `mode: read`, and/or (b) have the agent declare `exec` so the mode is resolvable. Worth confirming which layer is dropping the declaration.