@try-works/dsh-recursive-mode 0.4.5 → 0.4.6

package/lib/recursive_ask.tool.d.ts

@@ -125,24 +125,101 @@ export declare function createRecursiveAskTool(recursive: RecursiveRuntime): imp
 /**
  * PHASE 0 — record the answer to the run-start gate, and start the run only if it says so.
  *
- * ⚠ THIS GATE NEVER ACCEPTS A RELAYED ANSWER WHILE A HUMAN CHANNEL IS MOUNTED. That is the rule that makes
- * an approval a human act rather than an inference: when `ctx.userQuestions` is present, the question is
- * PUT TO THE PERSON and nothing else can settle it — not the caller's own `answer` argument, and not a
- * fabrication, because `ask()` resolves only with a real selection. A person's decline is likewise final
- * for that call and cannot be overridden by a model that asked for `Start run` in the same breath.
- *
- * ⚠ AND WHEN NO CHANNEL IS MOUNTED, THE RELAYED ANSWER IS THE ONLY POSSIBLE SOURCE, so it is used — that
- * is the same contract the other three gates have always had, and refusing it would leave a composition
- * without the channel unable to start any run at all. The question is surfaced first by the ASK branch
- * (the card data the host renders), and the model's `answer` is that person's selection coming back.
- *
- * ⚠ WHAT THE GATE THEREFORE DOES *NOT* CLAIM, stated rather than implied: in a composition with no
- * `userQuestions` channel, a plugin cannot verify that a person was really asked, so a model could in
- * principle relay a label nobody gave. That is a property of the relay, not of this gate — and it is the
- * reason the channel is consulted in preference whenever it exists. See the header of `run-start.ts`.
+ * ⚠ THREE OUTCOMES, AND TELLING THEM APART IS THE FIX. The first version of this function collapsed all of
+ * them into one `null`: "the channel threw", "the channel resolved with something unrecognisable", and
+ * "nobody answered" produced the same refusal, whose text asserted a cause ("so no person was asked") the
+ * plugin had already thrown away. A live session paid for that: the call failed after 22.9 s, the operator
+ * could not be told why, and the refusal's own advice prescribed the call that had just failed. So:
+ *
+ *   1. A PERSON WAS REACHED (`unusable`): the channel resolved, so somebody answered, and their answer is
+ *      not a label this gate offered — a skip, a custom value, several labels at once. That is a DECISION
+ *      the gate cannot record, and it is final: neither the caller's `answer` nor `relay=true` may replace
+ *      it. (RM5504)
+ *   2. THE CHANNEL FAILED (`unavailable`): no decision came back at all, and the refusal NAMES THE CAUSE
+ *      from the error the channel threw. Here the run can still be started, because a composition whose
+ *      channel cannot deliver the question would otherwise be unable to start any run — but only by the
+ *      caller asking for the relay in so many words (`relay=true`), which the result reports as
+ *      `source: "relayed"` rather than as a person's own selection. (RM5503)
+ *   3. NO CHANNEL IS MOUNTED: the relayed answer is the only possible source, exactly as before. (RM5502
+ *      when there is no answer either)
+ *
+ * ⚠ AND A CANCELLED OR CLOSED QUESTION IS NEVER RELAYABLE. `ASK_CANCELLED`, `ASK_ABORTED` and
+ * `ASK_TIMED_OUT` are the codes that mean the question was settled from outside this gate — the card was
+ * dismissed, the turn was cancelled, or a foreground window ended. The relay is refused for those, so a
+ * question the operator stopped cannot be turned into an approval by asking again in the same breath.
+ * Every other failure is a composition or capability failure — the question reached nobody — which is the
+ * class the relay exists for.
+ *
+ * ⚠ WHAT THE GATE STILL DOES *NOT* CLAIM: a relayed approval is a relayed approval. The plugin cannot
+ * verify that a person gave the label, and it does not pretend otherwise — the result's `source` and
+ * `channel` fields say where the decision came from, and a direct selection is preferred whenever the
+ * channel can produce one.
  */
 export declare function recordRunStartAnswer(recursive: RecursiveRuntime, root: string, runId: string, answer: string | undefined, exec: {
     agent?: unknown;
     signal?: unknown;
     callId?: unknown;
-}): Promise<Record<string, unknown>>;
+}, relay?: boolean): Promise<Record<string, unknown>>;
+/**
+ * PHASE 0 — WHAT THE BLOCKING CHANNEL ACTUALLY DID.
+ *
+ * ⚠ THIS TYPE EXISTS BECAUSE ITS ABSENCE WAS THE DEFECT. The first version returned a bare `null` from a
+ * `catch {}` for every failure and for every unrecognisable selection, so "the channel threw NO_PROVIDER",
+ * "the caller is not the live root agent", "the person skipped the question" and "the person typed a
+ * custom value" were ONE value. The refusal built from it then asserted the one cause it could not know.
+ * An outcome carries the cause, the raw message, and whether the failure is the class a relay may answer.
+ */
+export type RunStartChannelOutcome = 
+/** The person answered, and their selection is exactly one of the gate's own labels. */
+{
+    kind: 'answered';
+    answer: string;
+}
+/** The channel RESOLVED, so a person was reached — but the answer is not a label this gate offered. */
+ | {
+    kind: 'unusable';
+    detail: string;
+}
+/** The channel THREW: no decision came back, and the cause is named rather than discarded. */
+ | {
+    kind: 'unavailable';
+    cause: string;
+    detail: string;
+    relayable: boolean;
+};
+/**
+ * ⚠ THE CODES THAT MEAN THE QUESTION WAS CANCELLED OR CLOSED rather than never delivered: the person
+ * dismissed the card, their turn was cancelled, or a foreground window ended. A caller may not convert any
+ * of those into an approval by asking for the relay in the same breath. Every other failure means the
+ * question reached nobody — a composition or capability failure, which is the class the relay exists for.
+ */
+export declare const NON_RELAYABLE_CHANNEL_CODES: readonly ["ASK_CANCELLED", "ASK_ABORTED", "ASK_TIMED_OUT"];
+/**
+ * Name the failure of one `ask()` call, without inventing anything about it.
+ *
+ * The cause is the error's own `code` when it has one (the harness's `UserQuestionError` carries
+ * `NO_PROVIDER`, `CALLER_NOT_LIVE`, `DELEGATED_CALLER`, `ASK_ABORTED`, …), else its `name`, else its
+ * JavaScript type. `detail` keeps the message verbatim so a reader sees the channel's own words rather
+ * than this plugin's paraphrase — the paraphrase is exactly how the previous version came to assert a
+ * cause nobody had.
+ */
+export declare function classifyChannelFailure(err: unknown): {
+    cause: string;
+    detail: string;
+    relayable: boolean;
+};
+/**
+ * Ask the run-start question through the blocking channel and report WHAT HAPPENED.
+ *
+ * ⚠ THE CATCH IS THE POINT. It used to be `catch { return null }` — a blocking human question whose
+ * failure cause was erased at the exact moment the cause was the only thing worth knowing. Every path out
+ * of this function now says which path it was.
+ *
+ * The selection is filtered to the gate's OWN labels: a question a UI answered with a free-text custom
+ * value must not become an approval just because it arrived on the right channel.
+ */
+export declare function askRunStartDirectly(channel: NonNullable<RecursiveRuntime['userQuestionsChannel']>, exec: {
+    agent?: unknown;
+    signal?: unknown;
+    callId?: unknown;
+}): Promise<RunStartChannelOutcome>;

package/lib/recursive_closeout.tool.d.ts

@@ -4,5 +4,15 @@ import type { RecursiveRuntime } from './runtime.ts';
  * SESSION's workspace only (R1 workspace-scoping invariant). The run is resolved
  * via the session agent's cwd -> workspace registry; a runId outside the current
  * workspace is rejected.
+ *
+ * A RUN ID IS A NAME, NOT A PATH HERE TOO, and "outside the current workspace is rejected" is NOT enough
+ * on its own: `closeoutRun` joins the id onto the run layer and then writes a receipt under it, and its
+ * scoping check is `runDir.startsWith(runRoot)` — a string prefix test, not containment. A `..\` segment
+ * that lands on a SIBLING of the run layer passes that check whenever the sibling's name begins with
+ * `run`, so a path-shaped id can still receive a write. MEASURED pre-fix: `..\run-away` and `../run-away`
+ * were accepted and reached the report; the other shapes below were stopped only by the sibling not
+ * existing, which is the operator's filesystem deciding, not the tool. The rule is `run-id.ts`; this
+ * boundary is where the name enters, so this is where it is refused, with `recursive_init`'s refusal shape
+ * — `BAD_RUN_ID` (RM1107), same detail sentence.
  */
 export declare function createRecursiveCloseoutTool(recursive: RecursiveRuntime): import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/recursive_init.tool.d.ts

@@ -13,5 +13,13 @@ import type { RecursiveRuntime } from './runtime.ts';
  * rather than "this call created something": re-initialising an APPROVED run reports `approved: true`
  * (and the run keeps its goal), which is what a caller re-scaffolding a run it already started needs to
  * see.
+ *
+ * AND A RUN ID IS A NAME, NOT A PATH. This is the boundary where the name enters, so it is the boundary
+ * that refuses a path-shaped one — loudly, and before `initRun` can mkdir anything. The check lives here
+ * (through the shared `run-id.ts` rule) rather than in `runtime.ts` because `initRun` is not the only
+ * caller and because the runtime's `join(root, '.recursive', 'run', runId)` is CORRECT for a name; what
+ * was missing was a gate on the name. Teaching the runtime to accept a path would silently relocate the
+ * run layer instead of rejecting the call. See `run-id.ts` for the rule, the evidence behind it, and the
+ * "do not fix this back" note.
  */
 export declare function createRecursiveInitTool(recursive: RecursiveRuntime): import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/recursive_phase.tool.d.ts

@@ -5,5 +5,13 @@ import type { RecursiveRuntime } from './runtime.ts';
  * (runtime.phaseRules -> phaseRulesFor) as the once-per-phase pre-step
  * reminder, so the agent can re-ask for the rules without re-injecting them on
  * every step. Returns { error } when no active phase is found.
+ *
+ * A RUN ID IS A NAME, NOT A PATH HERE TOO, INCLUDING WHEN IT IS OMITTED. Omitted and path-shaped are
+ * different cases and must stay different: omitted means "the latest run by mtime", which `resolveRunDir`
+ * answers by DISCOVERY rather than by joining anything, and that case is untouched below. A path-shaped id,
+ * by contrast, is joined by `phaseRules` -> `resolveRunDir` and then read, and `recordInjection` WRITES
+ * `memory-injections.json` under whatever directory it resolved to — with no scoping check at all on this
+ * path. So the gate fires only on an id that was actually supplied, and `run-id.ts` owns the rule. The
+ * refusal is `recursive_init`'s, `BAD_RUN_ID` (RM1107), composed identically.
  */
 export declare function createRecursivePhaseTool(recursive: RecursiveRuntime): import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/recursive_scratch.tool.d.ts

@@ -3,5 +3,15 @@ import type { RecursiveRuntime } from './runtime.ts';
  * `recursive_scratch` — read/write/append the run-scoped disposable scratchpad
  * (R5) under the CURRENT session workspace only (R1). Scratch is git-ignored
  * and never citable as an Input.
+ *
+ * A RUN ID IS A NAME, NOT A PATH HERE TOO. `scratchRun` joins it onto the run layer, and it then WRITES
+ * (write/append) into the directory it landed on, so a path-shaped id does not merely fail to find a run:
+ * with a `..\` segment it can find and write into a SIBLING of the run layer, because the runtime's
+ * workspace-scoping check is `runDir.startsWith(runRoot)` — a string prefix test, not containment — and a
+ * sibling directory whose name begins with `run` passes it. MEASURED pre-fix: `..\run-away` was accepted
+ * and `scratchRun` wrote `scratch.md` into `<workspace>\.recursive\run-away\scratch\`. The rule is
+ * `run-id.ts`; the gate sits here, at the boundary where the name enters, rather than in `scratchRun`, for
+ * the same reason `recursive_init`'s does. Refusal shape is `recursive_init`'s, `BAD_RUN_ID` (RM1107),
+ * composed identically: one rule, one message.
  */
 export declare function createRecursiveScratchTool(recursive: RecursiveRuntime): import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/recursive_worktree.tool.d.ts

@@ -3,5 +3,21 @@ import type { RecursiveRuntime } from './runtime.ts';
  * `recursive_worktree` — create a linked git worktree for a run and/or
  * promote a branch up the dev/stage/main chain. Workspace-scoped: the
  * operations run under the SESSION's control-plane root only.
+ *
+ * A RUN ID IS A NAME, NOT A PATH HERE TOO, and this is the worst place to be without the rule: a `create`
+ * builds TWO things out of the id — the linked worktree directory `.worktrees/<runId>` AND the git branch
+ * `recursive/<runId>` (git accepts '/' inside a ref) — so a path-shaped id used to leave a worktree and a
+ * ref behind, not just a folder. MEASURED pre-fix, per id, against a fresh repo: `nested/child-run`
+ * returned ok:true and created BOTH `.worktrees/nested/child-run` and
+ * `refs/heads/recursive/nested/child-run`, while the shapes git itself refuses as ref syntax
+ * (`recursive//tmp/x`, `recursive/C:…`, `.hidden-run`, a trailing space) failed the worktree add and
+ * created neither. The rule is `run-id.ts` and is not restated here; the gate sits at this boundary, ahead
+ * of `createRunWorktree`, so the refusal no longer depends on git happening to dislike the ref name.
+ *
+ * The refusal is `BAD_RUN_ID` (RM1107), composed exactly as `recursive_init` composes it — same code, same
+ * detail, same sentence. One message for one rule is what keeps a caller from having to learn a second
+ * vocabulary for the same defect, and the shared remedy it carries ("call recursive_init again") is right
+ * for this tool as well: a `create` for a run that does not exist yet is exactly what `recursive_init`
+ * with `createWorktree: true` does.
  */
 export declare function createRecursiveWorktreeTool(recursive: RecursiveRuntime): import("@deepseek-ai/dsh-tools").ToolDefinition;

package/lib/run-id.d.ts

@@ -0,0 +1,62 @@
+/**
+ * A RUN ID IS A NAME, NOT A PATH.
+ *
+ * WHY THIS MODULE EXISTS. Every consumer of a run id JOINS it onto a directory
+ * that already carries the meaning "the run layer":
+ *
+ *     join(root, '.recursive', 'run', runId)   // runtime.ts, run.ts, handoff.ts, scratch.ts
+ *     join(repoRoot, '.worktrees', runId)      // worktree.ts (a linked worktree)
+ *     'recursive/' + runId                     // worktree.ts (the run's git branch)
+ *
+ * `join` is a PATH operation: absolute paths, drive specifiers and `..` segments
+ * are all legal input to it, and each one silently changes what the call means.
+ * A caller who passes `E:\tmp\rm-live-diagnostics\01-calculator-lib` is asking
+ * for a run "on another drive"; what they get is a `mkdir` of
+ *
+ *     <workspace>\.recursive\run\E:\tmp\rm-live-diagnostics\01-calculator-lib
+ *
+ * which is not drive-qualified at all — on POSIX and Windows alike the colon is
+ * just another character in a relative component. The result is a bogus nested
+ * folder INSIDE the workspace, created before anything can refuse it, surfacing
+ * far away as an ENOENT-shaped runtime failure (RM5501) with the operator's
+ * filesystem already dirty.
+ *
+ * SO THE RULE IS ENFORCED WHERE THE NAME ENTERS, and NOT by teaching the runtime
+ * to accept a path. The joins in `runtime.ts` are CORRECT for a name; what was
+ * missing was a gate on the name. Do not "fix" this back: a run on another drive
+ * or in a worktree is reached through the session's control-plane root
+ * (`recursive_worktree`, `00-worktree.md`) — the run layer is never relocated by
+ * smuggling a path into the id.
+ *
+ * The charset below is deliberately the SAME one the read path already uses
+ * (`live-route.ts` `DOC_SAFE_RE`) so a name this gate accepts is a name that
+ * route can serve.
+ */
+/**
+ * The accepted shape, as prose that can be embedded in a model-facing parameter
+ * description and in a refusal detail, so the rule is stated once.
+ */
+export declare const RUN_ID_RULE = "letters, digits, dot, underscore or dash only, no leading or trailing dot, no path separator, no drive specifier and no \"..\" segment";
+/** Two ids in the shapes the scaffold convention actually produces. */
+export declare const RUN_ID_EXAMPLES = "01-calculator-lib, fixture-run";
+/**
+ * Longest run id accepted. Directory-name components cap at 255 bytes on NTFS
+ * and ext4; a run id also becomes a git ref component (`recursive/<runId>`) and
+ * a prefix of every lock/receipt filename inside the run, so the ceiling is set
+ * well below the filesystem limit rather than at it.
+ */
+export declare const RUN_ID_MAX_LENGTH = 100;
+/**
+ * Why a run id is refused, or `null` when it is a usable NAME.
+ *
+ * The returned string is the SPECIFIC problem (which rule the id broke), with no
+ * trailing punctuation and no sentence of its own, so a caller can hand it to
+ * `toolError('BAD_RUN_ID', …)` as the detail. `RUN_ID_RULE` states the shape.
+ *
+ * The order of the checks is part of the message quality: a Windows absolute
+ * path is reported as a drive-qualified path (what the caller passed) rather
+ * than as a separator complaint (what that path is made of).
+ */
+export declare function runIdProblem(raw: string): string | null;
+/** True when `raw` is a usable run NAME. Convenience for callers that only branch. */
+export declare function isValidRunId(raw: string): boolean;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@try-works/dsh-recursive-mode",
   "description": "recursive-mode workflow as a DeepSeek Harness bundle: RecursiveRuntime service + 13 recursive_* tools (recursive_status, recursive_init, recursive_lock, recursive_lint, recursive_closeout, recursive_scratch, recursive_worktree, recursive_phase, recursive_audit_team, recursive_review, recursive_delegate, recursive_ask, recursive_preview)",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/src/errors.ts

@@ -65,12 +65,30 @@ export const TOOL_ERRORS = {
     problem: 'this gate has no default artifact, so one must be named',
     next: 'pass artifact: <file> so the answer has somewhere durable to land',
   },
+  RELAY_ONLY_FOR_RUN_START: {
+    code: 'RM1150',
+    klass: 'input',
+    problem: 'relay applies only to the run-start gate, which is the only gate that asks the user-questions channel',
+    next: 'drop relay for this gate and answer it with one of its own labels, or call recursive_ask with gate: run-start when the decision is whether to start the run',
+  },
   MISSING_RUN_ID: {
     code: 'RM1101',
     klass: 'input',
     problem: 'runId is required',
     next: 'call recursive_status with no runId to see the latest run id in this workspace',
   },
+  /**
+   * A run id is the NAME of the run directory and is joined onto the run layer
+   * as one path segment, so a path-shaped id is refused before any directory is
+   * created. See `run-id.ts` for the rule and for why it is not the runtime that
+   * learns to accept a path.
+   */
+  BAD_RUN_ID: {
+    code: 'RM1107',
+    klass: 'input',
+    problem: 'runId is not a single directory name',
+    next: 'pass the run directory name such as 03-something, then call recursive_init again',
+  },
   MISSING_ARTIFACT: {
     code: 'RM1102',
     klass: 'input',
@@ -153,11 +171,26 @@ export const TOOL_ERRORS = {
     problem: 'the run-start gate needs an answer, and this composition mounts no user-questions channel to ask one directly',
     next: 'call recursive_ask with gate: run-start and no answer to surface the question, then retry with answer: ' + '"Start run"',
   },
+  /**
+   * ⚠ RM5503 USED TO LIE. Its text asserted "so no person was asked" for EVERY cause, because the caller
+   * that produced it had already thrown the cause away — and a live session showed the cost: the gate
+   * failed 22.9 s into the call with a reason nobody could see, and its `Next:` clause prescribed the very
+   * call that had just failed, so no route to start a run remained. The problem statement now claims only
+   * what the gate knows (no decision came back), and the cause travels in the `detail` the caller
+   * supplies. `RUN_START_ANSWER_UNUSABLE` carries the one case this entry must NOT cover: a person was
+   * reached and their answer was not an approval.
+   */
   RUN_START_UNANSWERED: {
     code: 'RM5503',
     klass: 'runtime',
-    problem: 'the user-questions channel mounted in this composition refused the run-start question, so no person was asked',
-    next: 'use recursive_ask without an answer to surface the question, and retry it with answer: ' + '"Start run" once the user has approved the run start',
+    problem: 'the run-start question reached no decision: the mounted user-questions channel failed before a person answered it',
+    next: 'read the cause named in the detail, fix it and call recursive_ask again, or - when this composition cannot deliver the question at all - call recursive_ask with answer: ' + '"Start run"' + ' and relay=true to record the person\'s explicit approval as a relayed one',
+  },
+  RUN_START_ANSWER_UNUSABLE: {
+    code: 'RM5504',
+    klass: 'runtime',
+    problem: 'a person was asked to start this run and their answer was not one of the labels the run-start gate offered',
+    next: 'call recursive_ask again and have the person choose exactly "Start run" or "Hold"; a skipped or custom answer is not an approval, and no relayed answer can replace a decision the person made',
   },
   RUNTIME_REFUSED: {
     code: 'RM5501',