@sabaiway/agent-workflow-kit 1.45.1 → 1.47.0

package/tools/detect-backends.mjs

@@ -80,6 +80,9 @@ const RAW_BACKENDS = [
           blocked: ['-c*', '--config*', '-s*', '--sandbox*', '--dangerously-bypass-approvals-and-sandbox', '--dangerously-bypass-hook-trust', '--full-auto', '--oss', '--local-provider*', '-p*', '--profile*', '-m*', '--model*', '-o*', '--output-last-message*', '--json*', '--color*', '--output-schema*', '--ephemeral*'],
           probeRelaxed: ['--add-dir*', '-C*', '--cd*', '--skip-git-repo-check', '--ignore-rules', '--enable*', '--disable*'],
         },
+        notes: [
+          'nested-sandbox limit: codex-exec ships its OWN OS sandbox (bwrap workspace-write) and cannot run nested inside a harness sandbox (the FS turns read-only) — route it OUTSIDE the harness sandbox (excludedCommands / a per-run consented bypass) on the OBSERVED bwrap/EPERM failure, never a preemptive blanket',
+        ],
       },
       review: {
         invocations: [
@@ -122,6 +125,9 @@ const RAW_BACKENDS = [
           'agy-review --conversation <id> [--decided @f] [--focus "…"]',
         ],
         receipt: "side effect — a successful review appends one JSON receipt line to <git dir>/agent-workflow-review-receipts.jsonl (AW_REVIEW_RECEIPTS overrides; plan/diff outside a git tree: warn + skip unless overridden): fingerprint = sha256 over the canonical uncommitted-state payload (staged diff + unstaged diff + untracked-not-ignored contents — the review-payload domain; never-committable untracked paths — character/block devices, FIFOs, sockets — are excluded from the domain entirely, untracked symlinks/directories ride as name-only notes) in code mode, the artifact-file sha256 in plan/diff mode; verdict recorded verbatim from the mandated '### Verdict' section (SHIP / SHIP WITH NITS / REWORK); grounded = whether a NON-EMPTY --facts payload was supplied (an empty payload records grounded:false — fail-closed, the state gate rejects it), factsHash = sha256 of the facts payload; a continuation receipt is fresh:false (informational-only — it cannot attest the folded tree); a write failure warns, never fails the review",
+        notes: [
+          'pre-dispatch host-diff: before the FIRST dispatch of this bridge, diff its declared networkHosts against the live sandbox allow-list — a missing host is surfaced to the maintainer BEFORE dispatching, never fired into a known prompt',
+        ],
       },
     },
     bin: 'agy',

package/tools/doc-parity.mjs

@@ -27,7 +27,14 @@ import { SCHEMA_VERSION, REVIEW_CAP, V4_CLASSES, V4_OVERRIDE_SCOPES } from './re
 import { HARD_MAX, DEFAULT_DIFF_CAP } from './review-ledger-write.mjs';
 import { RESULT_SCHEMA_VERSION } from './fold-completeness.mjs';
 import { EXIT as DOCTOR_EXIT, STATUS as DOCTOR_STATUS, TRUSTED_DIRS as DOCTOR_TRUSTED_DIRS } from './autonomy-doctor.mjs';
-import { RECOMMENDATIONS_SECTION_HEADER, RECOMMENDATIONS_EMPTY_LINE } from './recommendations.mjs';
+import {
+  RECOMMENDATIONS_SECTION_HEADER,
+  RECOMMENDATIONS_EMPTY_LINE,
+  VERDICT_ATTENTION_TEMPLATE,
+  VERDICT_NOTHING_BROKEN,
+  VERDICT_OPTIONAL_TEMPLATE,
+  VERDICT_SKIPS_TEMPLATE,
+} from './recommendations.mjs';
 
 const KIT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -75,11 +82,16 @@ export const BINDINGS = Object.freeze([
     .filter((token) => token !== DOCTOR_STATUS.usage)
     .map((token) => valueBinding(`doctor-status:${token}`, token, token, [AUTONOMY_DOCTOR_DOC])),
   valueBinding('doctor-trusted-dirs', DOCTOR_TRUSTED_DIRS.join(':'), DOCTOR_TRUSTED_DIRS.join(':'), [AUTONOMY_DOCTOR_DOC]),
-  // The upgrade Recommendations section contract (AD-044 Plan 4): the section header and the
-  // exact empty-state line must render in BOTH the mode doc and upgrade.md (both exits reference
-  // them) — a reworded doc would silently break the paste-verbatim contract.
+  // The upgrade Recommendations section contract (AD-044 Plan 4 + REC-UX-REWORK D1): the section
+  // header, the exact empty-state line, and the frozen verdict templates must render in BOTH the
+  // mode doc and upgrade.md (both exits reference them) — a reworded doc would silently break the
+  // presentation contract (facts/counts complete, commands byte-exact).
   valueBinding('recommendations-header', RECOMMENDATIONS_SECTION_HEADER, RECOMMENDATIONS_SECTION_HEADER, [RECOMMENDATIONS_DOC, UPGRADE_DOC]),
   valueBinding('recommendations-empty-line', RECOMMENDATIONS_EMPTY_LINE, RECOMMENDATIONS_EMPTY_LINE, [RECOMMENDATIONS_DOC, UPGRADE_DOC]),
+  valueBinding('verdict-attention', VERDICT_ATTENTION_TEMPLATE, VERDICT_ATTENTION_TEMPLATE, [RECOMMENDATIONS_DOC, UPGRADE_DOC]),
+  valueBinding('verdict-nothing-broken', VERDICT_NOTHING_BROKEN, VERDICT_NOTHING_BROKEN, [RECOMMENDATIONS_DOC, UPGRADE_DOC]),
+  valueBinding('verdict-optional', VERDICT_OPTIONAL_TEMPLATE, VERDICT_OPTIONAL_TEMPLATE, [RECOMMENDATIONS_DOC, UPGRADE_DOC]),
+  valueBinding('verdict-skips', VERDICT_SKIPS_TEMPLATE, VERDICT_SKIPS_TEMPLATE, [RECOMMENDATIONS_DOC, UPGRADE_DOC]),
 ].map((b) => Object.freeze(b)));
 
 // ── the pure checker (readText is injectable for hermetic tests) ────────────────────────

package/tools/manifest/schema.md

@@ -19,6 +19,7 @@ expansion), never via the shell. The validator is [`validate.mjs`](./validate.mj
 | `detect` | object | no | `installed` (skill on the machine) + `deployed` (substrate set up in cwd) |
 | `settings` | array | no | the bridge's **settings-file surface** (typed; see *Settings*). Unlike `contract`, a malformed entry **fails** `--strict`. |
 | `networkHosts` | string[] | no | the backend CLI's **observed egress host families** (see *Network hosts*). A malformed list **fails** `--strict`. |
+| `writableDirs` | object[] | no | the backend CLI's **writable state-dir declarations** — `{env, default}` entries (see *Writable dirs*). A malformed list **fails** `--strict`. |
 | `install` / `uninstall` | object | no | `install.npm` is a package name, not a path |
 | `cost` / `quota` / `provenance` | misc | no | informational |
 | `available` | boolean | no | `false` = a declared-but-not-installed stub; skips fs/version checks |
@@ -105,10 +106,36 @@ source** for a hand-applied sandbox/network allowlist (session sandbox config, o
 - Observed-minimal, honestly incomplete: a blocked host names itself at run time — extend the
   hand-applied list by hand; the manifest list records what was actually observed.
 
+## Writable dirs (REC-UX-REWORK, D6)
+
+`writableDirs` declares the backend CLI's **writable state dirs** (credentials, session state) as
+`{env, default}` entries — a bare string cannot be truthful, because a wrapper resolves its state
+dir from an env override first (e.g. `CODEX_HOME` as `~`, `~/…`, absolute or relative), so the
+declared path is only the **default under no override**. Rules:
+
+- Each entry: `env` is `null` or an **UPPER_SNAKE_CASE env-var name**; `default` is a
+  **`~/`-anchored or absolute POSIX path** — no globs, no trailing slash, no `..` traversal.
+  Defaults must be unique. A malformed list **fails** `--strict` (the resolved dir is rendered
+  into a hand-applied recipe line by the Recommendations advisor).
+- **Resolution is the advisor's, at run time, mirroring the wrapper's byte-semantics:** a
+  NON-EMPTY env value wins (an EMPTY env value ≡ unset — the `${VAR:-default}` form); the
+  wrapper's exact case-arms apply — `~`, `~/…` and absolute forms ride as-given, EVERY other
+  form (including `~user/…`, which the wrappers never resolve as a home path) anchors like a
+  relative path. The advisor anchors those to the **target project root** (its pinned `--cwd`),
+  matching what a wrapper invoked from the project root resolves — the documented dispatch form
+  (the wrapper itself anchors to its invocation `$PWD`); else the `default` applies.
+- Like `networkHosts`, this is a **documentation source**: the kit never seeds
+  `sandbox.filesystem.allowWrite` or any other filesystem allowance — the entries feed the
+  sandbox-lane discoverability item (session/host sandbox config is hand-applied territory).
+
 ## Path-field rules (Windows-safe, traversal-safe)
 
-- **No absolute paths**, **no `..` traversal**, **no unresolved placeholders** (`{{…}}` / `${…}`)
-  in any field.
+These rules govern the **repo/project-relative path fields** enumerated below (`source`,
+`template`, `detect.*`) — NOT `writableDirs`, whose `default` entries are deliberately
+`~/`-anchored or absolute **host** paths under their own section's rules above.
+
+- **No absolute paths**, **no `..` traversal** in the fields below; **no unresolved placeholders**
+  (`{{…}}` / `${…}`) in any field.
 - `source`, `template`, `detect.installed.file` — repo-relative **within the skill**; must exist
   (skipped for `available:false` stubs).
 - `detect.installed.default` — may be **home-relative** (`~/…`); resolved by the installer.

package/tools/manifest/validate.mjs

@@ -339,6 +339,44 @@ export const validateManifest = (skillDir) => {
     }
   }
 
+  // `writableDirs` (REC-UX-REWORK, D6): the backend CLI's writable state-dir declarations —
+  // {env, default} entries the Recommendations advisor RESOLVES at run time (a NON-EMPTY env
+  // value wins, else the default) and renders into the sandbox-lane recipe. Like `networkHosts`
+  // this is a DOCUMENTATION source (the kit never seeds filesystem allowances), and a malformed
+  // list FAILS --strict for the same reason: the resolved dir is rendered into a hand-applied line.
+  const writableDirs = manifest.writableDirs;
+  if (writableDirs != null) {
+    if (!Array.isArray(writableDirs) || writableDirs.length === 0) {
+      errors.push('`writableDirs` must be a non-empty array of {env, default} entries');
+    } else {
+      const seenDefaults = new Set();
+      writableDirs.forEach((entry, i) => {
+        const at = `\`writableDirs[${i}]\``;
+        if (entry == null || typeof entry !== 'object' || Array.isArray(entry)) {
+          errors.push(`${at} must be an {env, default} object`);
+          return;
+        }
+        if (entry.env !== null && (typeof entry.env !== 'string' || !/^[A-Z][A-Z0-9_]*$/.test(entry.env))) {
+          errors.push(`${at}.env must be null or an UPPER_SNAKE_CASE env-var name (${JSON.stringify(entry.env)})`);
+        }
+        const dir = entry.default;
+        if (typeof dir !== 'string' || !(dir.startsWith('~/') || dir.startsWith('/'))) {
+          errors.push(`${at}.default must be a \`~/\`-anchored or absolute POSIX path (${JSON.stringify(dir)})`);
+          return;
+        }
+        if (/[*?[\]]/.test(dir)) errors.push(`${at}.default must not carry glob characters ("${dir}")`);
+        // The resolved dir is rendered into a ONE-LINE hand-applied recipe — a control character
+        // (newline, CR, NUL, …) would break the line or the shell paste.
+        // eslint-disable-next-line no-control-regex
+        if (/[\x00-\x1f\x7f]/.test(dir)) errors.push(`${at}.default must not carry control characters (${JSON.stringify(dir)})`);
+        if (dir.endsWith('/')) errors.push(`${at}.default must not end with a trailing slash ("${dir}")`);
+        if (hasTraversal(dir)) errors.push(`${at}.default must not contain ".." traversal ("${dir}")`);
+        if (seenDefaults.has(dir)) errors.push(`duplicate writableDirs default "${dir}" (${at})`);
+        else seenDefaults.add(dir);
+      });
+    }
+  }
+
   if (!isStub) {
     const auth = readAuthoritativeVersion(skillDir);
     if (auth.version == null) errors.push(`could not resolve an authoritative version (${auth.from})`);

package/tools/procedures.mjs

@@ -296,7 +296,10 @@ const costLanesAdvice = () => [
   '  • L2 subscription bridge (codex / agy) — reviews per the resolved recipe above, on frontier bridge models (quality-first).',
   '  • L3 frontier — judgment: plan/fold/synthesis, ADR/handover/changelog-entry wording, persuasive copy, go/no-go, real code.',
   '  • A step with no named guardrail does not move down a lane; red lines never move down (council review models · real code · memory/copy wording · the maintainer approval asks).',
-  '  • Sandbox lanes (under an OS sandbox): the L0 surfaces are sandbox-safe — gates/ledger/state/fold checks, git reads, plain no-network tests; the bridge wrappers are genuinely unsandboxed (network); npm-cache-touching commands are COMMAND-SHAPE dependent — first try the sandbox-safe shape (cache under $TMPDIR, offline/notifier off). Move ONLY the failing command out of the sandbox, never its class; BATCH consecutive unsandboxed calls.',
+  '  • Sandbox lanes (under an OS sandbox): the L0 surfaces are sandbox-safe — gates/ledger/state/fold checks, git reads, plain no-network tests; the bridge wrappers are genuinely unsandboxed (network); npm-cache-touching commands are COMMAND-SHAPE dependent — first try the sandbox-safe shape (cache under $TMPDIR, offline/notifier off). Move ONLY the failing command out of the sandbox, never its class; BATCH consecutive unsandboxed calls. Pre-dispatch host-diff: before the FIRST dispatch of each bridge, diff its manifest networkHosts against the live sandbox allow-list — a missing host is surfaced to the maintainer BEFORE dispatching, never fired into a known prompt. Nested-sandbox honesty: a backend CLI shipping its OWN OS sandbox cannot run nested inside a harness sandbox — route it outside (excludedCommands / a per-run consented bypass) on the OBSERVED failure, never a preemptive blanket.',
+  '  • Prompt economy (autonomy-preserving dispatch): read-only fan-out (research/sweeps/extraction) runs ONLY on restricted-tool vehicles — a full-tool subagent for read-only work is a forbidden lane downgrade (invisible prompt-flood + blast radius), and a subagent is never told to shell out for facts obtainable read-only; the orchestrator\'s own shell form is ONE plain pipeline per call (a ;/&& chain or env-prefixed invocation never matches a prefix allow rule); a fan-out LAUNCHER that gates per call yields to the agent-spawn lane. Capability-gated: on a host with restricted-tool subagent vehicles use them; without restricted-tool vehicles (a host offering only full-tool agents included), read-only research stays in the orchestrator\'s own context — never a vehicle mandate a host cannot satisfy.',
+  '  • Writer economy (autonomy-preserving dispatch): a stage\'s repeated WRITER commands batch into ONE invocation — combine a stage\'s writers via one batched write or one launcher per stage; never one writer call at a time (each write is its own prompt).',
+  '  • The prompt-economy clause narrows TOOLS for read-only work only — judgment, code, synthesis stay at the frontier lane; a task that genuinely needs to run or write keeps a full-tool subagent. Honest limit: no deterministic gate classifies a dispatch — enforcement is the canon at the point of use + the placed vehicles + the retro loop.',
 ];
 
 // The verbatim per-backend DRIVING CONTRACT block (M-contract): the exact invocation descriptor(s),
@@ -318,6 +321,10 @@ const contractLines = ({ cmd, contract, settings }) => {
   if (contract.passthrough) {
     lines.push(`        passthrough after '--' is ${contract.passthrough.policy}: blocked always: ${contract.passthrough.blocked.join(' ')}; relaxed only under CODEX_PROBE=1: ${contract.passthrough.probeRelaxed.join(' ')}`);
   }
+  // Contract notes — a TYPED renderer (AD-054): a manifest note MUST render here, else adding a
+  // notes[] key would silently disappear (the manifest validator tolerates unknown keys). Drift-
+  // guarded both directions against the manifest AND each wrapper's --help.
+  for (const note of contract.notes ?? []) lines.push(`        note: ${note}`);
   // Host-level settings knobs this wrapper honors (fact-only, from the bundled manifests; explicit
   // branch — contractLines drops any contract key it does not name, so this must be enumerated here).
   if ((settings ?? []).length) {