@erclx/aitk 3.53.0 → 3.55.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "3.53.0",
+  "version": "3.55.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/claude-orchestrate/references/orchestrator-poll.md

@@ -75,3 +75,13 @@ Coverage is what it buys over the poll. A worker that finishes goes idle and a w
 It classifies nothing and routes nothing. A line it prints says a pull request opened or a worker moved, and the routing block above is still what decides whether a review follows, so the two compose rather than replace each other.
 
 Every session in the repository holding a branch other than the base one counts as a worker, whoever launched it. The prototype matched the `orchestrator-` prefix instead, which reads a dispatched worker and misses every hand-launched one. A failed read of either source reports itself on a `watch:` line and leaves the baseline untouched, since reading an empty result as current state would report every worker gone on the pass after.
+
+## The stall alarm
+
+`watch.sh` prints `WORKER-STOPPED <name> <branch> <dwell>s` once a `waiting` row crosses `STALL_THRESHOLD_S`, and `WORKER-UNMEASURABLE <name> <branch>` for one whose record carries neither timestamp the dwell falls back to. Both are prints, not alerts, so the operator learns of one only when a session already reading the loop's output relays it further. The toolkit ships no notification verb, since the surface a stall reaches the operator through is a session tool rather than a command a shell loop can call.
+
+The two lines carry different confidence and the push has to say so rather than treat them as one signal. `WORKER-STOPPED` fires only once the dwell has already crossed the threshold, so it reports a wait already confirmed long. `WORKER-UNMEASURABLE` has no dwell to threshold on, so it fires on the first pass that meets a `waiting` row carrying neither stamp, whether that row has sat five seconds or fifty minutes.
+
+On meeting either line, push a notification to the operator through whatever notification surface the client offers, `PushNotification` in this repository's client and one example among the surfaces a different client exposes. Name the worker, the branch, which of the two lines fired, and the dwell where `WORKER-STOPPED` carries one, and send it once per stall the same way `watch.sh` prints it once, rather than repeating it on every interval the row stays stopped.
+
+The bound stays open. The alarm reaches the operator only through the controller's own read, so a controller mid-turn does not see the line for as long as the turn runs, and a controller that is itself stopped never does. Neither case closes here, since the watch loop and the notification surface both live inside the same session that has to be free to act on either.

package/docs/agents/sandbox.md

@@ -25,16 +25,20 @@ Scenario categories: `infra:*` (domain flows), `git:*`, `scaffold:*`. `create` s
 aitk sandbox check claude:docs drift --json
 ```
 
-| Flag                | Effect                                                     |
-| ------------------- | ---------------------------------------------------------- |
-| `--envelope <file>` | Read `is_error`, `num_turns`, denials, and the reply text  |
-| `--writes <file>`   | Newline-delimited paths the session wrote, for write scope |
-| `--json`            | Emit the verdict record on stdout                          |
-| `--strict`          | Exit 1 on `unchecked` instead of 0                         |
+| Flag                | Effect                                                                      |
+| ------------------- | --------------------------------------------------------------------------- |
+| `--envelope <file>` | Read `is_error`, `num_turns`, denials, and the reply text                   |
+| `--writes <file>`   | Newline-delimited paths the session wrote, for write scope                  |
+| `--escapes <file>`  | Newline-delimited paths written to a watched toolkit root, for escape scope |
+| `--escapes-watched` | At least one watched root held a target this run                            |
+| `--json`            | Emit the verdict record on stdout                                           |
+| `--strict`          | Exit 1 on `unchecked` instead of 0                                          |
 
 The verdict `state` is `pass`, `fail`, or `unchecked`. An arm with no `expect.toml` is `unchecked` and exits 0, so the harness stays usable while expectations roll out. A declaration that exists but asserts nothing is a failure, since an expectation file that asserts nothing passes every run.
 
-Omitting `--writes` or `--envelope` does not silently drop the assertion kinds that need them. Write scope, the turn ceiling, and the reply assertion report as unchecked and appear in the count, so the standalone command cannot claim more coverage than it had. A verdict never reports `pass` with zero assertions.
+Omitting `--writes`, `--escapes`, or `--envelope` does not silently drop the assertion kinds that need them. Write scope, escape scope, the turn ceiling, and the reply assertion report as unchecked and appear in the count, so the standalone command cannot claim more coverage than it had. Supplying `--escapes` without `--escapes-watched` reports the same way: a zero-escape result with no root confirmed watched is unmeasured rather than a pass. A verdict never reports `pass` with zero assertions.
+
+An arm declaring `escape_scope` asserts a bound on `run.sh`'s own escape watch rather than on the sandbox tree. `write_scope` skips when the run wrote nothing, since a required output missing is itself a finding, but `escape_scope` passes on zero escapes outright, since a clean run producing none is the expected outcome for a destination nothing requires a skill to touch, provided `--escapes-watched` confirms a root held something to watch. Declaring `escape_scope = []` asserts that a correct run reaches none of the watched destinations at all. `.claude/context/sandbox/overview.md` names what the watch reaches and what it cannot.
 
 An envelope that parses but carries no `result` field skips the reply assertion the same way an absent file does. An envelope carrying an empty `result` fails it, since a run that returned no text is a finding rather than a gap in the input.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "3.53.0",
+  "version": "3.55.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/src/commands/sandbox.ts

@@ -76,6 +76,8 @@ const CLEAN_ENVELOPE: RunEnvelope = { isError: false, turns: 0, denials: 0 }
 interface CheckOptions {
   readonly envelope?: string
   readonly writes?: string
+  readonly escapes?: string
+  readonly escapesWatched?: boolean
   readonly json?: boolean
   readonly strict?: boolean
 }
@@ -152,11 +154,13 @@ function readEnvelope(path: string | undefined): RunEnvelope | undefined {
 }
 
 /**
- * Undefined when no file was given, which is not the same as a run that wrote
- * nothing. The write-scope assertion needs that distinction: an empty list is a
- * finding, an absent list is a gap in what the caller supplied.
+ * Shared by `--writes` and `--escapes`, which are both a newline-delimited
+ * path list written by `run.sh`. Undefined when no file was given, which is
+ * not the same as a run that produced no paths. Write scope and escape scope
+ * both need that distinction: an empty list is a finding, an absent list is a
+ * gap in what the caller supplied.
  */
-function readWrites(path: string | undefined): string[] | undefined {
+function readPathList(path: string | undefined): string[] | undefined {
   if (path === undefined) return undefined
   if (!existsSync(path)) return []
 
@@ -360,7 +364,12 @@ function runCheck(
     expectFilePath(PROJECT_ROOT, parsed.category, parsed.command, arm ?? ''),
     {
       sandboxDir,
-      writes: readWrites(options.writes),
+      writes: readPathList(options.writes),
+      escapes: readPathList(options.escapes),
+      escapesWatched:
+        options.escapes === undefined
+          ? undefined
+          : options.escapesWatched === true,
       envelope: readEnvelope(options.envelope),
     },
   )
@@ -404,6 +413,14 @@ export function register(program: Command): void {
     .helpOption('-h, --help', 'Show this help message')
     .option('--envelope <file>', 'Run envelope JSON from claude -p')
     .option('--writes <file>', 'Newline-delimited paths the session wrote')
+    .option(
+      '--escapes <file>',
+      'Newline-delimited paths written to a watched toolkit root, for escape scope',
+    )
+    .option(
+      '--escapes-watched',
+      'At least one watched root held a target this run, so a zero-escape file is a clean watch rather than one with nothing to watch',
+    )
     .option('--json', 'Emit the verdict as JSON on stdout')
     .option('--strict', 'Exit non-zero when the arm declares no expectation')
     .addHelpText(

package/src/sandbox/expect.ts

@@ -19,6 +19,13 @@ export interface Expectation {
   readonly absent: readonly string[]
   readonly content: readonly ContentAssertion[]
   readonly writeScope: readonly string[]
+  /**
+   * Undefined means the arm makes no claim about escapes, which is every arm
+   * today. Present, even as `[]`, means the arm asserts a bound: the empty
+   * form declares that a correct run produces none, so `stringArray`'s
+   * collapse of "absent" and "empty" into one `[]` would erase that claim.
+   */
+  readonly escapeScope?: readonly string[]
   readonly reply: readonly string[]
   readonly manual: readonly string[]
   readonly maxTurns?: number
@@ -54,15 +61,23 @@ export interface Verdict {
 }
 
 /**
- * `writes` and `envelope` are absent when the caller supplied no data for them,
- * which is not the same as a run that wrote nothing or reported nothing. The
- * assertion kinds that depend on them report as skipped rather than silently
- * dropping out of the count, so the cheap standalone path cannot claim more
- * coverage than it had.
+ * `writes`, `escapes`, and `envelope` are absent when the caller supplied no
+ * data for them, which is not the same as a run that wrote nothing, escaped
+ * nowhere, or reported nothing. The assertion kinds that depend on them report
+ * as skipped rather than silently dropping out of the count, so the cheap
+ * standalone path cannot claim more coverage than it had.
  */
 export interface CheckInput {
   readonly sandboxDir: string
   readonly writes?: readonly string[]
+  readonly escapes?: readonly string[]
+  /**
+   * Whether any watched escape root held one of the four directories this run.
+   * Undefined when the caller supplied no escapes at all, which already skips.
+   * False is what separates a watch that ran and found nothing from one with
+   * nothing to watch, both of which produce the same empty `escapes` list.
+   */
+  readonly escapesWatched?: boolean
   readonly envelope?: RunEnvelope
 }
 
@@ -187,6 +202,10 @@ export function parseExpectation(source: string): Expectation {
     absent: stringArray(parsed.absent),
     content: contentArray(parsed.content),
     writeScope: stringArray(parsed.write_scope),
+    escapeScope:
+      parsed.escape_scope === undefined
+        ? undefined
+        : stringArray(parsed.escape_scope),
     reply: stringArray(parsed.reply),
     manual: stringArray(parsed.manual),
     maxTurns:
@@ -205,6 +224,7 @@ export function countMechanicalAssertions(expectation: Expectation): number {
     expectation.absent.length +
     expectation.content.length +
     expectation.writeScope.length +
+    (expectation.escapeScope === undefined ? 0 : 1) +
     expectation.reply.length
   )
 }
@@ -326,7 +346,7 @@ function checkWriteScope(
   // none, and without this the declaration vanishes from the verdict entirely:
   // no result, no skipped entry, and no contribution to the unchecked count that
   // exists to surface exactly this. The `undefined` branch above cannot stand in,
-  // since `run.sh` always passes `--writes` and `readWrites` returns `[]` for an
+  // since `run.sh` always passes `--writes` and `readPathList` returns `[]` for an
   // empty file. An arm whose output escaped the snapshot reads as a clean run,
   // which is the vacuous pass the harness exists to remove.
   if (writes.length === 0) {
@@ -348,6 +368,65 @@ function checkWriteScope(
   }
 }
 
+/**
+ * `run.sh` watches two toolkit roots for a write to shared session scratch
+ * during a run, and reports every one it finds as an unattributed escape with
+ * no arm able to fail on it. An arm whose skill legitimately reaches outside
+ * the sandbox tree declares the destinations here, and the harness asserts
+ * them instead of trusting the skill to bound itself.
+ *
+ * Declaring the scope inverts the empty case against `checkWriteScope`. A
+ * write-scope declaration exists to bound required output, so a run that wrote
+ * nothing skips rather than passing on a fabricated zero. An escape-scope
+ * declaration exists to bound a side effect nothing requires, so zero escapes
+ * is the outcome a correct run produces and reports as a pass outright,
+ * provided a watched root held something to watch. `run.sh`'s `snapshot_root`
+ * returns an empty manifest both when a watch ran clean and when none of the
+ * four watched directories existed under a root, and the two produce the same
+ * empty `escapes` list. `watched` is what tells them apart: a run that had
+ * nothing to watch reports unmeasured rather than passing on a diff it never
+ * had the target to take.
+ */
+function checkEscapeScope(
+  expectation: Expectation,
+  escapes: readonly string[] | undefined,
+  watched: boolean | undefined,
+): KindOutcome {
+  if (expectation.escapeScope === undefined) return { results: [], skipped: [] }
+
+  if (escapes === undefined) {
+    return {
+      results: [],
+      skipped: ['escape scope: no escape data supplied, pass --escapes'],
+    }
+  }
+
+  if (escapes.length === 0) {
+    if (watched === false) {
+      return {
+        results: [],
+        skipped: ['escape scope: no watched root held a target, unmeasured'],
+      }
+    }
+
+    return {
+      results: [{ ok: true, message: 'no escape during this run' }],
+      skipped: [],
+    }
+  }
+
+  const globs = expectation.escapeScope.map((glob) => new Bun.Glob(glob))
+
+  return {
+    results: escapes.map((path) =>
+      globs.some((glob) => glob.match(path))
+        ? { ok: true, message: `declared escape: ${path}` }
+        : { ok: false, message: `unbounded escape: ${path}` },
+    ),
+    skipped: [],
+  }
+}
+
 /**
  * Plain substrings, matched case-sensitively, against the text the run replied
  * with. A substring rather than a regex because the pattern a reply assertion
@@ -431,6 +510,11 @@ export function checkExpectation(
   input: CheckInput,
 ): Verdict {
   const scope = checkWriteScope(expectation, input.writes)
+  const escapeScope = checkEscapeScope(
+    expectation,
+    input.escapes,
+    input.escapesWatched,
+  )
   const reply = checkReply(expectation, input.envelope)
   const envelope = checkEnvelope(expectation, input.envelope)
 
@@ -440,9 +524,15 @@ export function checkExpectation(
     ...checkContent(expectation, input.sandboxDir),
     ...reply.results,
     ...scope.results,
+    ...escapeScope.results,
     ...envelope.results,
   ]
-  const skipped = [...scope.skipped, ...reply.skipped, ...envelope.skipped]
+  const skipped = [
+    ...scope.skipped,
+    ...escapeScope.skipped,
+    ...reply.skipped,
+    ...envelope.skipped,
+  ]
 
   const failed = results.filter((result) => !result.ok).length