@cohortapp/agent-sdk 2.12.0 → 2.13.0

package/plugins/maestro-skills/vendor/unlazy/scripts/lib/process-tree.mjs

@@ -0,0 +1,161 @@
+// Best-effort process-tree cleanup shared by the gate runner and tests.
+// Zero dependencies. Node 16+.
+
+import { spawnSync as nodeSpawnSync } from "node:child_process";
+import { win32 } from "node:path";
+
+export const WINDOWS_TASKKILL_TIMEOUT_MS = 1000;
+
+export function windowsTaskkillPath(env = process.env) {
+  const normalizeRoot = (value) => String(value || "").replace(/\//g, "\\").replace(/\\+$/, "");
+  const systemRoot = normalizeRoot(env.SystemRoot);
+  const windir = normalizeRoot(env.WINDIR);
+  const systemDrive = String(env.SystemDrive || "").replace(/[\\/]+$/, "").toUpperCase();
+  const driveRoot = /^[A-Za-z]:\\Windows$/i;
+  // Require the three standard Windows launcher values to identify the same
+  // drive-root directory. A single arbitrary absolute variable must not select
+  // an executable, and disagreement fails closed to the ChildProcess handle.
+  if (driveRoot.test(systemRoot) && driveRoot.test(windir) &&
+      systemRoot.toLowerCase() === windir.toLowerCase() &&
+      systemDrive === systemRoot.slice(0, 2).toUpperCase()) {
+    return win32.join(systemRoot, "System32", "taskkill.exe");
+  }
+  // A bare executable name consults cwd/PATH, which are controlled by the
+  // CHECK environment. If neither trusted system root exists, skip the helper
+  // and use the already-held ChildProcess handle instead.
+  return null;
+}
+
+function syncFailure(result) {
+  if (!result) return "returned no result";
+  if (result.error) return result.error.code || result.error.message || "spawn error";
+  if (result.signal) return "signal " + result.signal;
+  if (result.status !== 0) return "exit " + String(result.status);
+  return null;
+}
+
+const childExited = (child) => child.exitCode !== null && child.exitCode !== undefined ||
+  child.signalCode !== null && child.signalCode !== undefined;
+
+export function terminateProcessTree(child, options = {}) {
+  const platform = options.platform || process.platform;
+  const spawnSyncImpl = options.spawnSyncImpl || nodeSpawnSync;
+  const killGroup = options.killGroup || process.kill;
+  const pid = child && child.pid;
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return { ok: false, fallback: false, diagnostic: "child PID is unavailable" };
+  }
+
+  if (platform !== "win32") {
+    // The gate runner launches a detached Node supervisor as the group leader
+    // and keeps it alive until the shell and inherited stdout/stderr close. If
+    // Node has already observed that supervisor exit, the numeric PGID no
+    // longer carries identity and may have been reused; never signal it.
+    if (childExited(child)) {
+      return { ok: true, fallback: false, diagnostic: "process supervisor already exited" };
+    }
+    try {
+      killGroup(-pid, "SIGKILL");
+      return { ok: true, fallback: false, diagnostic: null };
+    } catch (error) {
+      if (childExited(child)) {
+        return {
+          ok: true,
+          fallback: true,
+          diagnostic: "process-group kill failed (" + (error.code || error.message) + "); supervisor already exited",
+        };
+      }
+      try {
+        const requested = child.kill("SIGKILL");
+        if (requested === false) {
+          return {
+            ok: false,
+            fallback: true,
+            diagnostic: "process-group kill failed (" + (error.code || error.message) +
+              "); child fallback returned false",
+          };
+        }
+        return {
+          ok: true,
+          fallback: true,
+          diagnostic: "process-group kill failed (" + (error.code || error.message) + "); child fallback requested",
+        };
+      } catch (fallbackError) {
+        return {
+          ok: false,
+          fallback: true,
+          diagnostic: "process-group kill failed (" + (error.code || error.message) +
+            "); child fallback failed (" + (fallbackError.code || fallbackError.message) + ")",
+        };
+      }
+    }
+  }
+
+  // taskkill addresses the stored leader PID, unlike a POSIX process-group
+  // request. Do not target it after Node reports exit because the PID may have
+  // been reused while an inherited pipe remains open.
+  if (childExited(child)) {
+    return { ok: true, fallback: false, diagnostic: "child already exited" };
+  }
+
+  const command = windowsTaskkillPath(options.env || process.env);
+  const requestedTimeout = Number(options.taskkillTimeoutMs);
+  const taskkillTimeoutMs = Number.isFinite(requestedTimeout) && requestedTimeout > 0
+    ? Math.floor(requestedTimeout)
+    : WINDOWS_TASKKILL_TIMEOUT_MS;
+  let result;
+  let failure;
+  if (!command) {
+    failure = "trusted system taskkill path unavailable";
+  } else {
+    try {
+      result = spawnSyncImpl(command, ["/pid", String(pid), "/f", "/t"], {
+        stdio: "ignore",
+        windowsHide: true,
+        // Cleanup runs inside the gate timeout path. A broken helper must not
+        // replace a bounded CHECK with an unbounded synchronous wait.
+        timeout: taskkillTimeoutMs,
+        killSignal: "SIGKILL",
+      });
+      failure = syncFailure(result);
+    } catch (error) {
+      failure = error.code || error.message || "spawn threw";
+    }
+  }
+  if (!failure) return { ok: true, fallback: false, diagnostic: null, command };
+
+  if (childExited(child)) {
+    return {
+      ok: true,
+      fallback: true,
+      command,
+      diagnostic: "taskkill failed (" + failure + "); child already exited",
+    };
+  }
+
+  try {
+    const requested = child.kill("SIGKILL");
+    if (requested === false) {
+      return {
+        ok: false,
+        fallback: true,
+        command,
+        diagnostic: "taskkill failed (" + failure + "); child fallback returned false",
+      };
+    }
+    return {
+      ok: true,
+      fallback: true,
+      command,
+      diagnostic: "taskkill failed (" + failure + "); child fallback requested",
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      fallback: true,
+      command,
+      diagnostic: "taskkill failed (" + failure + "); child fallback failed (" +
+        (error.code || error.message) + ")",
+    };
+  }
+}

package/plugins/maestro-skills/vendor/unlazy/scripts/lib/regex-worker.mjs

@@ -0,0 +1,9 @@
+import { parentPort } from "node:worker_threads";
+
+parentPort.once("message", ({ source, flags, output }) => {
+  try {
+    parentPort.postMessage({ matched: new RegExp(source, flags).test(output) });
+  } catch (error) {
+    parentPort.postMessage({ error: error.message });
+  }
+});

package/plugins/maestro-skills/vendor/unlazy/templates/PLAN.md

@@ -0,0 +1,116 @@
+# Plan: <task>
+
+Scope: <validated pipeline id; store this file at .unlazy/<scope>/PLAN.md>
+Depth: tree <N>
+Mode: orchestrated
+
+## Contract
+
+Decide before fan-out:
+
+- Interfaces: <signatures, schemas, formats, integration points>
+- Ownership: <one complete set of repository-relative paths per leaf; no absolute paths, traversal, or concurrent overlap>
+- Dependencies: <leaf ids that must be VERIFIED first>
+- Host launch mode: <Codex native subagents | Claude background Agents | Claude Dynamic Workflow | sequential fallback>
+- Wave policy: <which independent READY leaves launch together and the maximum host concurrency>
+- Toolchain: <runtime versions, shell, working-directory rules, test commands>
+- Conventions: <naming, errors, compatibility, formatting>
+- Manual review: <owner and evidence standard for consequential manual gates>
+
+## Current contract inventory
+
+Contract revision: 1. Before fan-out, reread the original request and current amendments. Record every independently omittable required outcome and every constraint that changes acceptance; do not copy credentials, private text, or unrelated context.
+
+| ID | Required outcome or constraint | Owner | Observing gate or manual review | Disposition | Revision |
+|---|---|---|---|---|---|
+| C1 | <concise paraphrase> | <leaf/node> | <qualified gate/reviewer> | ACTIVE | 1 |
+
+Use stable ids. On an amendment, increment the revision and reconcile every affected row before dispatch or completion credit. `ACTIVE` is complete only with a current owner and observation. `ABANDONED`, `DEFERRED`, and `OWNER_DECISION` are honest non-completion; only explicit user authority may use `REMOVED_BY_USER`.
+
+## State vocabulary
+
+Leaf state is exactly one of:
+
+- WAITING: at least one id in Needs is not VERIFIED
+- READY: dependencies are VERIFIED and ownership can be claimed
+- IN-FLIGHT: dispatched, not yet parent-verified
+- VERIFIED: parent --reverify passed and manual gates were reviewed
+- ABANDONED: a required gate has a visible handoff
+
+Branch state is exactly one of OPEN, VERIFIED, or ABANDONED. Derive root and
+branch state from their ledgers; do not copy it into the topology tree.
+
+## Tree
+
+Use this tree only for parent-child topology and ledger paths. Use `leaf-` paths
+for work leaves and `node-` paths for branch integration. Keep leaf operational
+fields only in the dispatch table below; do not repeat `Owns`, `Needs`, `Tier`,
+`Planned wave`, or `State` here and do not create a separate schedule.
+
+- 1 <task> .............. GATES.md
+  - 1.1 <branch> ........ gates/node-1.1.md
+    - 1.1.1 <leaf> ...... gates/leaf-1.1.1.md
+    - 1.1.2 <leaf> ...... gates/leaf-1.1.2.md
+  - 1.2 <branch> ........ gates/node-1.2.md
+    - 1.2.1 <leaf> ...... gates/leaf-1.2.1.md
+    - 1.2.2 <leaf> ...... gates/leaf-1.2.2.md
+
+## Leaf dispatch table
+
+This is the single authoritative PLAN table for leaf operation. It is
+authoritative for `Needs`, `Tier`, `Planned wave`, and `State`; `Owns` remains
+visible here as the derived planning mirror described below. Keep exactly one
+row per tree leaf and do not duplicate these fields in the tree or a schedule.
+
+| Leaf | Owns | Needs | Tier | Planned wave | State |
+|---|---|---|---|---|---|
+| 1.1.1 | src/<a>/**, tests/<a>/** | - | mechanical | 1 | READY |
+| 1.1.2 | src/<b>/**, tests/<b>/** | - | judgment | 1 | READY |
+| 1.2.1 | src/<c>/**, tests/<c>/** | - | mechanical | 1 | READY |
+| 1.2.2 | src/<d>/**, tests/<d>/** | 1.2.1 | judgment | 2 | WAITING |
+
+`Owns` is a derived planning mirror of the complete glob set in the leaf ledger.
+The ledger's `OWNS:` header is the command-time authority read by `--claim`.
+Normalize both into sets and require equality before marking the row `READY` and
+again before each claim. On disagreement, fail closed, correct and log the plan
+or ledger, and recheck; never guess ownership. A successful claim does not prove
+the mirror agreed with the ledger.
+
+`Tier` is planner metadata for execution leaves. Use `judgment` when a leaf's own
+artifact needs design or review, and `mechanical` only when its pattern and gates
+are fixed. Map a tier through documented host-specific model or reasoning
+controls only when the host exposes them. Otherwise retain the tier as a briefing
+and review requirement without claiming a model choice. Driver and branch duties,
+including planning, dispatch, parent verification, integration, and final audit,
+remain judgment responsibilities outside this leaf field. Tier never weakens a
+leaf's gates, parent re-verification, or integration standard.
+
+`Planned wave` is the earliest intended launch group under the current contract.
+Use a positive integer, put every dependency in an earlier planned wave, and let
+the wave policy cap concurrency. It is a plan, not a barrier: rolling dispatch
+may start a later planned wave as soon as that row's dependencies are verified,
+without waiting for unrelated work. Actual starts belong in `dispatch.json` and
+`status.log`; do not add a second schedule to this file.
+
+Change `Needs`, `Owns`, `Tier`, or `Planned wave` only through a recorded plan
+amendment before that row launches; do not erase a dependency when it becomes
+satisfied. Update `State` in this table as work progresses. After parent
+re-verification and manual review, mark a leaf `VERIFIED`, release that exact
+leaf lease, and record the release. Do not promote a dependent until that exact
+release is recorded. For an abandoned leaf, record the handoff and confirm its
+worker has settled before releasing only that leaf; never call it
+parent-verified. Release the whole scope only after every leaf is settled and
+final scope verification has run. If final verification reports a handoff,
+record it before release and never describe the scope as complete.
+
+## Status log
+
+Append events to `.unlazy/<scope>/status.log`; do not copy the event history into this file:
+
+```text
+node <skill-dir>/scripts/gate-check.mjs --scope <scope> --log "leaf-1.1.1 dispatched"
+node <skill-dir>/scripts/gate-check.mjs --scope <scope> --log "leaf-1.1.1 verified"
+node <skill-dir>/scripts/gate-check.mjs --scope <scope> --log "leaf-1.1.1 lease released"
+```
+
+Record contract amendments, plan changes, dispatch, parent verification, abandonment, branch integration, and lease release. Apply logged plan amendments and live State updates only in the dispatch table; keep the log append-only. Before root completion, reread the current request and review every current inventory row against its owner and observing gate or manual review.

package/plugins/maestro-skills/vendor/unlazy/templates/gates-leaf.md

@@ -0,0 +1,51 @@
+# Gates: <leaf or task name>
+
+OWNS: <repository-relative globs this leaf may write, for example src/api/**, tests/api/**>
+
+Scope: <one sentence describing the complete deliverable>
+
+- [ ] G1: <observable outcome measured directly from the artifact>
+  CHECK: node scripts/verify-outcome.mjs
+  EXPECT: outcome verification passed
+  EVIDENCE: pending
+
+- [ ] G2: <integration outcome in a subproject>
+  CHECK: node scripts/verify-integration.mjs
+  EXPECT: integration verification passed
+  CWD: packages/example
+  EVIDENCE: pending
+
+- [ ] G3: <manual outcome that no command can decide>
+  EVIDENCE: pending
+
+<!--
+Replace every placeholder before running the checker.
+
+Strict format:
+- Use a unique explicit id for every gate.
+- Indent CHECK, EXPECT, CWD, and EVIDENCE.
+- Give a runnable gate both CHECK and EXPECT; give a manual gate neither.
+- Success requires process exit 0 and EXPECT.
+- Make EXPECT a success-only marker produced after every assertion passes.
+- For an absence or negative assertion, test the same checker against a known
+  positive fixture and record that control in the gate's manual review.
+- Measure supplied figures from source. Do not copy a supplied number into
+  EXPECT as its own proof.
+- Use repository-owned Node scripts for portable examples. Declare any
+  non-default shell or external tool requirement explicitly.
+- Scoped and legacy discovery anchor checks at the repository root. When this
+  ledger is named explicitly from `.unlazy/`, pass an explicit repository
+  `--root` and `--cwd` so repository-relative commands keep the same base.
+- Record exact manual evidence and review consequential manual gates by risk.
+- OWNS paths must be repository-relative, complete, and disjoint from every
+  concurrently dispatched leaf. Claims coordinate writers; they do not sandbox.
+
+If a gate becomes genuinely impossible, keep the gate and add:
+
+```text
+ABANDON: G<n> <non-empty reason and handoff>
+```
+
+Surface every abandonment as a non-successful handoff in the final report; an
+abandoned leaf is not complete. See references/gates.md.
+-->

package/plugins/maestro-skills/vendor/unlazy/templates/gates-node.md

@@ -0,0 +1,51 @@
+# Gates: <branch name> integration
+
+Scope: integrate children <explicit child ids> into one verified result
+
+- [ ] N1: every named direct child is reverified from its exact ledger
+  CHECK: node <skill-dir>/scripts/gate-check.mjs --root . --cwd . --reverify --jobs 1 .unlazy/<scope>/gates/leaf-<a>.md .unlazy/<scope>/gates/node-<b>.md
+  EXPECT: ALL MET
+  EVIDENCE: pending
+
+- [ ] N2: child interfaces match the contract in PLAN.md
+  CHECK: node scripts/verify-interfaces.mjs
+  EXPECT: interface verification passed
+  EVIDENCE: pending
+
+- [ ] N3: cross-child behavior works end to end
+  CHECK: node scripts/verify-integration.mjs
+  EXPECT: integration verification passed
+  EVIDENCE: pending
+
+- [ ] N4: affected sibling behavior has not regressed
+  CHECK: node scripts/verify-regressions.mjs
+  EXPECT: regression verification passed
+  EVIDENCE: pending
+
+- [ ] N5: every direct leaf child's ownership lease was released after parent verification
+  EVIDENCE: pending
+
+- [ ] N6: consequential manual outcomes from the children were reviewed at branch level
+  EVIDENCE: pending
+
+<!--
+Replace every placeholder before running the checker.
+
+N1 must name every direct child ledger explicitly, whether that child is a leaf
+or another branch, and use --reverify, not --status. Status validates the stored
+definition binding without executing or inspecting current artifacts. Keep --jobs 1 unless the child checks are independent and
+deterministic parallel execution is intentional.
+If a child reports an abandonment, N1 exits 1 with `HANDOFF REQUIRED`. Mark the
+branch ABANDONED and surface the handoff; never rewrite that result as completion.
+
+Branch paths use node-<id>.md. Leaf paths use leaf-<id>.md. Branch completion
+requires integration evidence; a set of locally complete leaves is not enough.
+
+For N5, run this once for each direct leaf child after verification and record
+the outputs as manual evidence. Branch children do not own leaf leases:
+
+node <skill-dir>/scripts/gate-check.mjs --scope <scope> --leaf leaf-<id> --release
+
+Drop N5 only when no child claimed ownership. See references/orchestration.md
+and references/parallel.md.
+-->