@open-agent-toolkit/cli 0.1.54 → 0.1.59

package/assets/skills/oat-worktree-bootstrap-auto/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-worktree-bootstrap-auto
-version: 1.4.0
+version: 1.5.6
 description: Use when an orchestrator/subagent needs autonomous worktree bootstrap. Non-interactive companion to oat-worktree-bootstrap.
 argument-hint: '<branch-name> [--base <ref>] [--path <root>] [--baseline-policy <strict|allow-failing>]'
 disable-model-invocation: false
@@ -41,12 +41,13 @@ When this skill is executed, provide concise status updates:
   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 - Before major phases, print compact indicators, for example:
-  - `[1/6] Resolving worktree root…`
-  - `[2/6] Creating/reusing worktree…`
-  - `[3/6] Verifying resolved base in worktree HEAD…`
-  - `[4/6] Running baseline checks…`
-  - `[5/6] Syncing provider directories…`
-  - `[6/6] Returning structured status…`
+  - `[1/7] Resolving worktree root…`
+  - `[2/7] Detecting bootstrap mode from resolved base…`
+  - `[3/7] Creating/reusing worktree…`
+  - `[4/7] Verifying resolved base in worktree HEAD…`
+  - `[5/7] Running baseline checks…`
+  - `[6/7] Syncing providers or recording smoke skips…`
+  - `[7/7] Returning structured status…`
 
 ## Inputs
 
@@ -69,8 +70,15 @@ When this skill is executed, provide concise status updates:
 | `strict`        | Fail fast on any baseline check failure. Return error status immediately.                                  |
 | `allow-failing` | Continue on baseline failures. Emit structured warnings. Log failures to project artifacts when available. |
 
+The baseline policy never downgrades smoke containment failures. A missing,
+unsafe, or malformed smoke marker, or failure of the smoke-safe
+repository bootstrap path, is always fatal.
+
 ## Process
 
+Initialize `BOOTSTRAP_MODE=normal` at process entry so even failures before base
+inspection return an explicit mode. Only Step 1.5 may change it to `smoke`.
+
 ### Step 1: Resolve Worktree Root
 
 Use the same resolution precedence as `oat-worktree-bootstrap`:
@@ -86,19 +94,104 @@ Use the same resolution precedence as `oat-worktree-bootstrap`:
 
 If the resolved root is project-local (`.worktrees` or `worktrees`), verify it is gitignored.
 
+### Step 1.5: Resolve Base and Detect Bootstrap Mode
+
+Resolve the base commit and inspect that commit, not the caller's checkout or
+the eventual target, before any worktree creation command:
+
+```bash
+RESOLVED_BASE_SHA=$(git -C "$REPO_ROOT" rev-parse "$BASE_REF")
+BOOTSTRAP_MODE=normal
+SMOKE_MARKER_ENTRY=$(
+  git -C "$REPO_ROOT" ls-tree "$RESOLVED_BASE_SHA" -- ".oat/smoke-bootstrap.json"
+)
+if [[ -n "$SMOKE_MARKER_ENTRY" ]]; then
+  BOOTSTRAP_MODE=smoke
+fi
+```
+
+`BOOTSTRAP_MODE` is derived state, not a caller override. Set
+`BOOTSTRAP_MODE=smoke` only when the resolved base commit tracks the marker
+path. An absent path selects `normal`; a base-resolution or tree-inspection
+error is a bootstrap error. This detection must complete before Step 2.
+
 ### Step 2: Create or Reuse Worktree
 
 - Validate branch name: `^[a-zA-Z0-9._/-]+$`
 - Resolve target path: `{root}/{branch-name}`
-- If branch exists locally: `git worktree add "{target-path}" "{branch-name}"`
-- If branch does not exist: `git worktree add "{target-path}" -b "{branch-name}" "{base-ref}"`
-- If worktree already exists at target path: reuse it (validate branch matches)
+- In normal mode, preserve existing behavior:
+  - If the branch exists locally:
+    `git -C "$REPO_ROOT" worktree add "$TARGET_PATH" "$BRANCH_NAME"`
+  - If the branch does not exist:
+    `git -C "$REPO_ROOT" worktree add "$TARGET_PATH" -b "$BRANCH_NAME" "$BASE_REF"`
+  - If a worktree already exists at the target path, reuse it after validating
+    that its branch matches.
+- In smoke mode, disable repository hooks only for each create/reuse command
+  invocation. Never mutate persistent Git configuration:
+
+  ```bash
+  # Existing branch
+  git -c core.hooksPath=/dev/null -C "$REPO_ROOT" worktree add \
+    "$TARGET_PATH" "$BRANCH_NAME"
+
+  # New branch
+  git -c core.hooksPath=/dev/null -C "$REPO_ROOT" worktree add \
+    "$TARGET_PATH" -b "$BRANCH_NAME" "$BASE_REF"
+
+  # Reused target validation uses the same invocation-scoped suppression.
+  git -c core.hooksPath=/dev/null -C "$TARGET_PATH" \
+    rev-parse --abbrev-ref HEAD
+  ```
+
+  Do not run `git config core.hooksPath ...`; the suppression must remain
+  invocation-scoped.
+
+After smoke-mode creation or reuse, require the tracked marker in the target
+before any propagation, sync, status, or test command:
+
+```bash
+git -C "$TARGET_PATH" ls-files --error-unmatch -- ".oat/smoke-bootstrap.json"
+SMOKE_MARKER="$TARGET_PATH/.oat/smoke-bootstrap.json"
+test -d "$TARGET_PATH/.oat"
+test ! -L "$TARGET_PATH/.oat"
+test -f "$SMOKE_MARKER"
+test ! -L "$SMOKE_MARKER"
+```
+
+Any failed check is a fatal containment failure with
+`reason: smoke-marker-invalid`, regardless of baseline policy. Do not fall
+through to normal mode.
+
+Immediately after those marker checks, register the child from the parent
+orchestrator before running any command inside it:
+
+```bash
+SMOKE_MANIFEST=$(
+  node -e \
+    "const marker=require(process.argv[1]); process.stdout.write(marker.manifestPath)" \
+    "$SMOKE_MARKER"
+)
+node "$TARGET_PATH/tools/smoke/runner/journal.mjs" register \
+  --manifest "$SMOKE_MANIFEST" \
+  --marker "$SMOKE_MARKER" \
+  --worktree "$TARGET_PATH"
+```
+
+Registration is idempotent, so the repository's smoke-safe bootstrap may
+register the same child again. This parent-side registration must happen before
+the first child process: a package-manager, shell, or bootstrap-launch failure
+must not leave an unjournaled worktree that cleanup cannot safely own.
 
 On failure: return structured error, do not prompt.
 
 ### Step 2.5: Propagate Local-Only Config + Local Paths
 
-After the worktree is created or reused, copy gitignored local-only config and sync configured local paths.
+**Smoke mode:** skip source config propagation and `oat local sync` entirely.
+The safe init path owns the only permitted config transfer. Do not read or copy
+the invoking checkout's local-only config here.
+
+**Normal mode:** after the worktree is created or reused, copy gitignored
+local-only config and sync configured local paths as before.
 
 **Config propagation:**
 
@@ -126,11 +219,7 @@ oat local sync "$TARGET_PATH" 2>/dev/null || true
 
 Before any baseline checks run, verify the worktree actually branched from the resolved base. This catches host-native or git-internal misbehavior that would otherwise silently land the worktree at the wrong base.
 
-1. Resolve the base SHA:
-
-   ```bash
-   RESOLVED_BASE_SHA=$(git -C "$REPO_ROOT" rev-parse "$BASE_REF")
-   ```
+1. Reuse `RESOLVED_BASE_SHA` from Step 1.5.
 
 2. Capture the worktree HEAD:
 
@@ -149,23 +238,76 @@ Before any baseline checks run, verify the worktree actually branched from the r
 
 **On base mismatch:** treat as a bootstrap failure. Do **not** silently land at the wrong base, do **not** proceed to baseline checks. Apply the configured baseline policy to the failure:
 
+- `smoke` → return immediately with `status: failed` and
+  `reason: smoke-base-mismatch`. This is a containment failure and cannot be
+  downgraded by `allow-failing`.
 - `strict` → return immediately with `status: failed`, `reason: base-mismatch`, populated `expected_base_sha` and `observed_head_sha`, and the worktree path. The orchestrator is expected to cancel the dispatch and degrade.
 - `allow-failing` → emit a structured warning (`reason: base-mismatch`, with `expected_base_sha` and `observed_head_sha`), append a base-mismatch entry to `implementation.md` if an active project exists, and continue to Step 3 only if the caller has explicitly opted into a degraded outcome. In all other cases prefer fail-fast — base mismatch is rarely recoverable.
 
 ### Step 3: Run Baseline Checks
 
-Execute in the target worktree directory:
-
-```bash
-pnpm run worktree:init          # install + build + sync
-oat status --scope project
-pnpm test
-```
-
-Continue to Step 4 for provider directory setup, the `git_clean` baseline
-check, and the all-scope sync. The `git_clean` check must run after provider
-directory creation but before the all-scope sync sweep, so it measures inherited
-worktree state plus setup output rather than the sync sweep's generated output.
+Execute in the target worktree directory.
+
+First resolve the repository bootstrap contract:
+
+1. Read the applicable agent instructions and contributing/setup guidance.
+2. Inspect repository task definitions, manifests, and lockfiles.
+3. Prefer an explicit worktree bootstrap command when the repository declares
+   one.
+4. If no command exists, derive the minimum safe setup for a fresh worktree
+   from repository context.
+5. Select the repository's documented readiness check and a proportionate
+   baseline verification. Do not default to a full test suite when setup
+   guidance specifies a narrower readiness check.
+6. Record the exact selected commands and the evidence used to choose them.
+
+Never assume Node.js, pnpm, a dependency store, or a particular install, build,
+or test command. For example, this repository declares its own `worktree:init`
+procedure in `AGENTS.md` and `package.json`; that repository context, not this
+skill, supplies the invocation.
+
+**Normal mode:**
+
+Run the selected repository bootstrap, readiness, and baseline commands. Run
+`oat status --scope project` when the initialized repository contains an OAT
+project.
+
+Continue to Step 4 for normal provider directory setup, the `git_clean`
+baseline check, and the all-scope sync. The `git_clean` check must run after
+provider directory creation but before the all-scope sync sweep, so it measures
+inherited worktree state plus setup output rather than the sync sweep's
+generated output.
+
+**Smoke mode:**
+
+Source smoke preflight already owns dependency, build, and repository-wide test
+readiness for the source commit. A nested smoke child must run only the
+repository bootstrap's smoke-safe containment path: validate the marker,
+register ownership in the locked manifest journal, verify the expected base,
+copy and hash-check the provisioned config, and run fixture-scoped readiness
+checks.
+
+The smoke-safe path must not install dependencies, build the repository, run
+repository-wide tests, or invoke provider sync. Those operations are neither
+retried nor downgraded in a child. After containment succeeds, verify the
+fixture project artifacts and declared writable task files, then run
+`git status --porcelain`.
+
+The first command is the safe-init boundary. Any nonzero exit is a containment
+failure: return immediately with `status: failed` and
+`reason: smoke-init-failed`, regardless of whether the marker is missing,
+unsafe, or malformed or a journal/config/bootstrap check failed. Never
+apply `allow-failing` to that result. Run the remaining read-only/local checks
+only after safe init succeeds. Never run PATH-resolved `oat` in smoke mode; the
+built repository-local CLI entrypoint is the only permitted OAT executable.
+Invoke the repository's direct smoke-safe entrypoint, not a package-manager
+wrapper that may perform installation before reaching it. In this repository
+that command is `bash scripts/worktree/init.sh`, not
+`pnpm run worktree:init`.
+Set the child worktree itself as the process working directory. Use the
+equivalent of `(cd "$TARGET_PATH" && bash scripts/worktree/init.sh)`; invoking
+the child script by absolute path while the shell remains in the outer
+worktree is a containment failure.
 
 Check behavior per baseline policy:
 
@@ -183,8 +325,21 @@ Check behavior per baseline policy:
 
 ### Step 4: Create Provider Directories and Sync
 
-Worktrees do not inherit gitignored provider directories. Create them if
-missing, run the `git_clean` baseline check, and then run sync:
+**Smoke mode:** skip provider-directory creation, all-scope sync, staging, and
+sync commits. Do not run `mkdir` for provider views, `oat sync --scope all`,
+`git add`, or `git commit`. After the safe local status/test checks in Step 3,
+run only the final clean check:
+
+```bash
+git status --porcelain
+```
+
+Record `provider_sync: skip` and `sync_commit: skip`, plus every structured
+smoke skip listed in Step 5. Any dirty result is handled as the `git_clean`
+baseline check; it does not authorize cleanup, staging, or a commit.
+
+**Normal mode:** worktrees do not inherit gitignored provider directories.
+Create them if missing, run the `git_clean` baseline check, and then run sync:
 
 ```bash
 mkdir -p "{target-path}/.claude/skills"
@@ -224,22 +379,35 @@ branch: '{branch-name}'
 base_ref: '{base-ref}'
 resolved_base_sha: '{sha resolved from base-ref}'
 observed_head_sha: '{sha of worktree HEAD after add}'
+bootstrap_mode: normal | smoke
 checks:
-  worktree_init: pass | fail | skip
-  project_status: pass | fail | skip
-  tests: pass | fail | skip
+  repository_bootstrap: pass | fail | skip
+  repository_readiness: pass | fail | skip
+  baseline_verification: pass | fail | skip
+  smoke_child_readiness: pass | fail | skip
   git_clean: pass | fail | skip
   provider_sync: pass | fail | skip
   sync_commit: pass | fail | skip
+smoke_skips:
+  local_config_propagation: true | false
+  local_paths_sync: true | false
+  provider_directory_creation: true | false
+  provider_sync: true | false
+  sync_staging: true | false
+  sync_commit: true | false
 warnings: [] # List of warning messages (allow-failing mode)
 error: null # Error message (strict mode failure)
-reason: null # Structured reason on failure (e.g., base-mismatch)
+reason: null # e.g., base-mismatch, smoke-marker-invalid, smoke-init-failed, smoke-readiness-failed
 expected_base_sha: null # Populated when reason is base-mismatch
 baseline_policy: strict | allow-failing
 ```
 
 `resolved_base_sha` and `observed_head_sha` are populated on **every** terminal status (success, warning, error, failed) so callers can perform belt-and-suspenders post-verification on the success path as well as diagnose the failure path.
 
+`bootstrap_mode` is populated on every terminal status after Step 1.5.
+`smoke_skips` is explicit on every terminal status: all six values are `true`
+for smoke mode and `false` for normal mode.
+
 **Status determination:**
 
 - `success`: All checks passed and Step 2.7 base-resolution verification passed.
@@ -248,19 +416,31 @@ baseline_policy: strict | allow-failing
 - `error`: `sync_commit` failed under `strict` policy.
 - `warning`: `sync_commit` failed under `allow-failing` policy.
 - `failed` (with `reason: base-mismatch`): Step 2.7 base-resolution verification failed. Callers should treat this distinctly from a generic baseline error — it is a contract violation, not a flaky check.
+- `failed` (with `reason: smoke-marker-invalid`): smoke mode was detected from
+  the resolved base but the target marker is missing or unsafe.
+- `failed` (with `reason: smoke-init-failed`): the marker is malformed or the
+  safe-init containment path failed. Both smoke failure statuses are fatal
+  under `strict` and `allow-failing`.
+- `failed` (with `reason: smoke-readiness-failed`): fixture-scoped child
+  readiness failed after containment. Stop immediately; do not dispatch a
+  phase implementer, reviewer, or gate and do not degrade to sequential
+  execution.
 
 ## Error Handling
 
-| Scenario                                   | Behavior                                                                                                                   |
-| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
-| Worktree creation fails                    | Return error status with git error message                                                                                 |
-| Branch already checked out elsewhere       | Return error with worktree location info                                                                                   |
-| Base mismatch (Step 2.7 fails, strict)     | Return `status: failed`, `reason: base-mismatch`, with `expected_base_sha` and `observed_head_sha`. Do not run baselines.  |
-| Base mismatch (Step 2.7 fails, allow-fail) | Emit structured warning with `reason: base-mismatch`, log to artifacts, prefer fail-fast unless caller opted into degrade. |
-| Baseline check fails (strict)              | Return error with check name and failure output                                                                            |
-| Baseline check fails (allow-failing)       | Add to warnings, continue, log to artifacts                                                                                |
-| No active project                          | Skip artifact logging, use console only                                                                                    |
-| Invalid branch name                        | Return error before attempting creation                                                                                    |
+| Scenario                                   | Behavior                                                                                                                        |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| Worktree creation fails                    | Return error status with git error message                                                                                      |
+| Branch already checked out elsewhere       | Return error with worktree location info                                                                                        |
+| Smoke marker missing or unsafe             | Return `status: failed`, `reason: smoke-marker-invalid`; never run propagation, sync, status, or tests                          |
+| Smoke marker malformed or safe init fails  | Return `status: failed`, `reason: smoke-init-failed`; never downgrade under `allow-failing`                                     |
+| Smoke fixture readiness fails              | Return `status: failed`, `reason: smoke-readiness-failed`; abort the run before any phase implementer, reviewer, or gate launch |
+| Base mismatch (Step 2.7 fails, strict)     | Return `status: failed`, `reason: base-mismatch`, with `expected_base_sha` and `observed_head_sha`. Do not run baselines.       |
+| Base mismatch (Step 2.7 fails, allow-fail) | Emit structured warning with `reason: base-mismatch`, log to artifacts, prefer fail-fast unless caller opted into degrade.      |
+| Baseline check fails (strict)              | Return error with check name and failure output                                                                                 |
+| Baseline check fails (allow-failing)       | Add to warnings, continue, log to artifacts                                                                                     |
+| No active project                          | Skip artifact logging, use console only                                                                                         |
+| Invalid branch name                        | Return error before attempting creation                                                                                         |
 
 ## Artifact Logging
 
@@ -304,6 +484,10 @@ When a base mismatch is detected (Step 2.7) and an active project exists, append
 | `strict`        | Fail fast, return error immediately | Error in status output                     | `status: error`   |
 | `allow-failing` | Continue, collect warnings          | Append to `implementation.md` (or console) | `status: warning` |
 
+Containment failures are outside this table's baseline-failure policy. A
+missing, unsafe, or malformed smoke marker and any smoke safe-init failure are
+fatal under both policies.
+
 **Orchestrator integration:**
 
 - When invoked by `oat-project-implement` in parallel mode, the baseline policy is passed through from the orchestration run policy.
@@ -316,10 +500,15 @@ When a base mismatch is detected (Step 2.7) and an active project exists, append
 - **Never** create fallback artifact files — log to existing artifacts or console only.
 - **Never** modify implementation code — bootstrap and checks only.
 - **Never** override or conflict with `oat-worktree-bootstrap` manual-safe behavior.
+- **Never** propagate caller-local config, sync local paths/providers, stage, or
+  commit from smoke mode.
+- **Never** use a PATH-resolved `oat` executable for smoke checks.
 
 ## Success Criteria
 
 - Worktree exists and is on the correct branch.
+- Bootstrap mode was derived from the resolved base before creation.
 - Baseline checks executed per policy.
+- Smoke mode completed safe init without any skipped side-effect path running.
 - Structured status returned for orchestrator consumption.
 - Failures logged to appropriate destination without user interaction.

package/dist/commands/docs/index-generate/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/index-generate/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAI5C,eAAO,MAAM,uBAAuB,iIAC4F,CAAC;AAOjI,UAAU,6BAA6B;IACrC,aAAa,EAAE,CACb,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC,CAAC;IACjD,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,KAAK,MAAM,CAAC;IACrE,SAAS,EAAE,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,KACrB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,aAAa,EAAE,CACb,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,OAAO,oBAAoB,EAAE,SAAS,CAAC,CAAC;IACrD,cAAc,EAAE,CACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,oBAAoB,EAAE,SAAS,KAC3C,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACnD;AAED,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,QAAQ,EAAE,6BAA6B,CAAC;CACzC;AAgFD,wBAAgB,8BAA8B,CAC5C,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAsBT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/index-generate/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAI5C,eAAO,MAAM,uBAAuB,iIAC4F,CAAC;AAOjI,UAAU,6BAA6B;IACrC,aAAa,EAAE,CACb,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC,CAAC;IACjD,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,KAAK,MAAM,CAAC;IACrE,SAAS,EAAE,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,KACrB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,aAAa,EAAE,CACb,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,OAAO,oBAAoB,EAAE,SAAS,CAAC,CAAC;IACrD,cAAc,EAAE,CACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,oBAAoB,EAAE,SAAS,KAC3C,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACnD;AAED,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,QAAQ,EAAE,6BAA6B,CAAC;CACzC;AAqFD,wBAAgB,8BAA8B,CAC5C,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAsBT"}

package/dist/commands/docs/index-generate/index.js

@@ -35,11 +35,16 @@ async function runIndexGenerate(context, options, deps) {
     await deps.writeFile(outputPath, content, 'utf8');
     const repoRoot = await deps.resolveRepoRoot(context.cwd);
     const config = await deps.readOatConfig(repoRoot);
-    config.documentation = {
-        ...config.documentation,
-        index: relative(repoRoot, outputPath) || 'index.md',
-    };
-    await deps.writeOatConfig(repoRoot, config);
+    const indexPath = relative(repoRoot, outputPath) || 'index.md';
+    if (config.documentation?.index !== indexPath) {
+        await deps.writeOatConfig(repoRoot, {
+            ...config,
+            documentation: {
+                ...config.documentation,
+                index: indexPath,
+            },
+        });
+    }
     if (context.json) {
         context.logger.json({
             status: 'ok',

package/dist/commands/doctor/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/doctor/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/doctor/index.ts"],"names":[],"mappings":"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"}

package/dist/commands/doctor/index.js

@@ -313,11 +313,12 @@ async function resolveDoctorCodexMaxDepth(scope, parsedConfig, userHome, depende
     }
 }
 function createCodexMaxDepthCheck(scope, entry) {
-    const topology = 'root (0) → phase coordinator (1) → task worker (2)';
+    const topology = 'root (0) → phase implementer (1)';
+    const optionalTopology = 'optional nested child (2)';
     const numericDepth = typeof entry.value === 'number' && Number.isFinite(entry.value)
         ? entry.value
         : null;
-    const sufficient = numericDepth !== null && numericDepth >= 2;
+    const sufficient = !entry.present || (numericDepth !== null && numericDepth >= 1);
     let state;
     if (!entry.present) {
         state = 'agents.max_depth is missing';
@@ -330,10 +331,12 @@ function createCodexMaxDepthCheck(scope, entry) {
     }
     return {
         name: `${scope}:codex_max_depth`,
-        description: 'Codex managed-role nested dispatch depth',
+        description: 'Codex managed-role phase dispatch depth',
         status: sufficient ? 'pass' : 'warn',
         message: sufficient
-            ? `${state}; sufficient for ${topology}.`
+            ? numericDepth !== null && numericDepth >= 2
+                ? `${state}; sufficient for ${topology} and ${optionalTopology}.`
+                : `${state}; sufficient for ${topology}. Depth 2 enables ${optionalTopology} when useful.`
             : `${state}; OAT managed implementation requires ${topology}.`,
         fix: sufficient
             ? undefined

package/dist/commands/gate/index.d.ts

@@ -18,18 +18,26 @@ interface GateCommandDependencies {
     runProcess: (command: string, args: string[], options: ProcessRunOptions) => Promise<ProcessRunResult>;
     parseReviewGateVerdict: typeof parseReviewGateVerdict;
     processEnv: NodeJS.ProcessEnv;
+    writeDiagnostic: (message: string) => void;
 }
 interface ProcessRunOptions {
     cwd: string;
     env: NodeJS.ProcessEnv;
+    livenessIntervalMs?: number;
+    onLiveness?: (snapshot: GateLivenessSnapshot) => void;
     purpose: 'host-detection' | 'availability' | 'execute';
-    stdio: 'ignore' | 'inherit';
+    stdio: 'ignore' | 'inherit' | 'pipe';
     timeoutMs: number;
 }
 interface ProcessRunResult {
     exitCode: number;
     timedOut?: boolean;
 }
+interface GateLivenessSnapshot {
+    elapsedMs: number;
+    hardBudgetMs: number;
+    idleMs: number;
+}
 type CrossProviderAvoid = 'same-family' | 'same-runtime' | 'none';
 type GateDiversityAchieved = 'different-family' | 'degraded-to-different-slug' | 'same-family - no diverse target available' | 'unknown-producer';
 export interface SelectedExecTarget {

package/dist/commands/gate/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/gate/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/gate/index.ts"],"names":[],"mappings":"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"}

package/dist/commands/gate/index.js

@@ -29,6 +29,7 @@ const DEFAULT_DEPENDENCIES = {
     runProcess: runChildProcess,
     parseReviewGateVerdict,
     processEnv: process.env,
+    writeDiagnostic: (message) => process.stderr.write(message),
 };
 const VALID_ON_FAILURE = ['block', 'prompt', 'warn'];
 const VALID_WRITE_LAYERS = [
@@ -56,6 +57,7 @@ const VALID_IDENTITY_PROVENANCES = [
 const REVIEW_GATE_CONTEXT_NOTE = 'This review is gate-originated. If you run `oat-project-review-provide`, set `oat_review_invocation: gate` in the review artifact. Write a canonical review artifact with `### Critical`, `### Important`, `### Medium`, and `### Minor` headings in that order, using `None` for empty sections.';
 const GATE_CHECK_TIMEOUT_MS = 5_000;
 const GATE_EXEC_TIMEOUT_MS = 15 * 60 * 1_000;
+const GATE_LIVENESS_INTERVAL_MS = 30_000;
 function reviewGateProjectContext(project) {
     return [
         `Resolved OAT project path: ${project.path}. Run the review for this project path.`,
@@ -196,11 +198,35 @@ async function runChildProcess(command, args, options) {
     return new Promise((resolve, reject) => {
         let timedOut = false;
         let killTimeout = null;
+        const startedAt = Date.now();
+        let lastActivityAt = startedAt;
         const child = spawn(command, args, {
             cwd: options.cwd,
             env: options.env,
-            stdio: options.stdio,
+            stdio: options.stdio === 'pipe' ? ['inherit', 'pipe', 'pipe'] : options.stdio,
         });
+        const recordActivity = () => {
+            lastActivityAt = Date.now();
+        };
+        child.stdout?.on('data', (chunk) => {
+            recordActivity();
+            process.stdout.write(chunk);
+        });
+        child.stderr?.on('data', (chunk) => {
+            recordActivity();
+            process.stderr.write(chunk);
+        });
+        const livenessInterval = options.onLiveness && options.livenessIntervalMs
+            ? setInterval(() => {
+                const now = Date.now();
+                options.onLiveness?.({
+                    elapsedMs: now - startedAt,
+                    hardBudgetMs: options.timeoutMs,
+                    idleMs: now - lastActivityAt,
+                });
+            }, options.livenessIntervalMs)
+            : null;
+        livenessInterval?.unref();
         const timeout = setTimeout(() => {
             timedOut = true;
             child.kill('SIGTERM');
@@ -212,6 +238,9 @@ async function runChildProcess(command, args, options) {
         timeout.unref();
         child.on('error', (error) => {
             clearTimeout(timeout);
+            if (livenessInterval) {
+                clearInterval(livenessInterval);
+            }
             if (killTimeout) {
                 clearTimeout(killTimeout);
             }
@@ -219,6 +248,9 @@ async function runChildProcess(command, args, options) {
         });
         child.on('close', (code) => {
             clearTimeout(timeout);
+            if (livenessInterval) {
+                clearInterval(livenessInterval);
+            }
             if (killTimeout) {
                 clearTimeout(killTimeout);
             }
@@ -321,6 +353,17 @@ function resolveGateExecTimeoutMs(env) {
     }
     return parsed;
 }
+function resolveGateLivenessIntervalMs(env) {
+    const rawValue = env.OAT_GATE_LIVENESS_INTERVAL_MS?.trim();
+    if (!rawValue) {
+        return GATE_LIVENESS_INTERVAL_MS;
+    }
+    const parsed = Number(rawValue);
+    if (!Number.isInteger(parsed) || parsed < 1) {
+        return GATE_LIVENESS_INTERVAL_MS;
+    }
+    return parsed;
+}
 function parseArgvJson(value, flag) {
     let parsed;
     try {
@@ -827,6 +870,7 @@ async function executeTarget(selected, prompt, context, dependencies) {
         ? ['--model', selected.model]
         : [];
     const timeoutMs = resolveGateExecTimeoutMs(dependencies.processEnv);
+    const livenessIntervalMs = resolveGateLivenessIntervalMs(dependencies.processEnv);
     if (!context.json) {
         context.logger.info(`Running gate target ${selected.id} (${selected.target.runtime}); timeout=${timeoutMs}ms.`);
     }
@@ -834,8 +878,24 @@ async function executeTarget(selected, prompt, context, dependencies) {
         return await dependencies.runProcess(command, [...baseArgs, ...modelArgs, ...prompt], {
             cwd: context.cwd,
             env: dependencies.processEnv,
+            livenessIntervalMs,
+            onLiveness: ({ elapsedMs, hardBudgetMs, idleMs }) => {
+                const telemetry = {
+                    elapsedMs,
+                    hardBudgetMs,
+                    idleMs,
+                    target: selected.id,
+                    type: 'gate-liveness',
+                };
+                if (context.json) {
+                    dependencies.writeDiagnostic(`${JSON.stringify(telemetry)}\n`);
+                }
+                else {
+                    context.logger.info(`Gate liveness: target=${selected.id} elapsed_ms=${elapsedMs} idle_ms=${idleMs} hard_budget_ms=${hardBudgetMs}.`);
+                }
+            },
             purpose: 'execute',
-            stdio: 'inherit',
+            stdio: 'pipe',
             timeoutMs,
         });
     }