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

package/src/recursive_worktree.tool.ts

@@ -1,5 +1,6 @@
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { toolError } from './errors.ts'
+import { RUN_ID_EXAMPLES, RUN_ID_RULE, runIdProblem } from './run-id.ts'
 import type { JsonValue } from '@deepseek-ai/dsh-util-values'
 import type { RecursiveRuntime } from './runtime.ts'
 
@@ -7,13 +8,29 @@ 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 function createRecursiveWorktreeTool(recursive: RecursiveRuntime) {
   return defineTool({
     name: 'recursive_worktree',
     description: 'Create a linked git worktree for a recursive-mode run and/or promote a branch up the dev/stage/main chain. Workspace-scoped under the current session workspace.',
     parameters: {
-      runId: { type: 'string', description: 'Run id the worktree is created for (e.g. 03-something). Required for create.' },
+      runId: { type: 'string', description: 'Run id the worktree is created for — the NAME of the run (e.g. 03-something), never a path: ' + RUN_ID_RULE + '. A path-shaped id is refused for create. Required for create.' },
       action: { type: 'string', description: 'create | promote | status. Default: create.' },
       fromBranch: { type: 'string', description: 'Source branch for a promote action (the branch holding the new commits).' },
       toBranch: { type: 'string', description: 'Promotion target branch for a promote action (feature -> dev -> stage -> main).' },
@@ -35,7 +52,15 @@ export function createRecursiveWorktreeTool(recursive: RecursiveRuntime) {
         if (!args.runId || args.runId.trim() === '') {
           return { error: toolError('MISSING_CREATE_RUN_ID') } as const
         }
-        const result = recursive.createRunWorktree(root, args.runId.trim(), args.baseBranch?.trim() || undefined)
+        const runId = args.runId.trim()
+        // BEFORE `createRunWorktree`: that call builds `.worktrees/<runId>` and cuts the branch
+        // `recursive/<runId>`, so a path-shaped id that reaches it has already created both. The gate is
+        // on the name; `run-id.ts` says why the join itself is not the thing to change.
+        const problem = runIdProblem(runId)
+        if (problem !== null) {
+          return { error: toolError('BAD_RUN_ID', problem + ' - run ids allow ' + RUN_ID_RULE + ' - e.g. ' + RUN_ID_EXAMPLES) } as const
+        }
+        const result = recursive.createRunWorktree(root, runId, args.baseBranch?.trim() || undefined)
         return result as unknown as JsonValue
       }
       if (action === 'promote') {

package/src/run-id.ts

@@ -0,0 +1,100 @@
+/**
+ * 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 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 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 const RUN_ID_MAX_LENGTH = 100
+
+/** Directory-name charset — the read path's `DOC_SAFE_RE`, verbatim. */
+const RUN_ID_CHARS = /^[A-Za-z0-9._-]+$/
+
+/**
+ * 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 function runIdProblem(raw: string): string | null {
+  if (raw === '') return 'runId is empty'
+  if (raw.length > RUN_ID_MAX_LENGTH) return 'runId is ' + raw.length + ' characters, over the ' + RUN_ID_MAX_LENGTH + ' allowed'
+  // A Windows drive-QUALIFIED path (`E:\x`, and the drive-relative `E:x` too).
+  if (/^[A-Za-z]:/.test(raw)) return 'runId is a Windows drive-qualified path, starting with "' + raw.slice(0, 2) + '"'
+  // Path separators: an absolute POSIX path, a UNC path, or any nested path.
+  if (raw.includes('/') || raw.includes('\\')) {
+    return 'runId contains the path separator "' + (raw.includes('/') ? '/' : '\\') + '"'
+  }
+  // A colon that is not a drive prefix is still unmappable on Windows (NTFS
+  // alternate data streams), and the run id is a Windows directory name.
+  if (raw.includes(':')) return 'runId contains a colon (":"), which is a drive and stream separator on Windows'
+  // `..` makes the join resolve to the PARENT of the run layer.
+  if (raw.includes('..')) return 'runId contains a ".." segment, which escapes the run directory'
+  // `.` and `..` are the parent/current directory segments, and a trailing dot is
+  // stripped by the Win32 path parser — `03-foo.` and `03-foo` would then be two
+  // names for one directory.
+  if (raw.startsWith('.')) return 'runId starts with ".", which makes it a hidden name or a relative path segment'
+  if (raw.endsWith('.')) return 'runId ends with "."'
+  if (!RUN_ID_CHARS.test(raw)) {
+    // Whitespace inside the name is called out separately because the caller can
+    // see the id they typed and cannot see why it is refused: the tool trims the
+    // ENDS (so `" 03-x "` already names `03-x`), but an interior space is not
+    // normalized anywhere and would create a directory the caller cannot retype.
+    if (/\s/.test(raw)) return 'runId contains a space or other whitespace character inside the name'
+    return 'runId contains a character outside the allowed set'
+  }
+  return null
+}
+
+/** True when `raw` is a usable run NAME. Convenience for callers that only branch. */
+export function isValidRunId(raw: string): boolean {
+  return runIdProblem(raw) === null
+}

package/src/run-start.ts

@@ -20,9 +20,15 @@
  *      and nothing else, so the presence of a `Run Start` line is never on its own consent.
  *   2. IT IS ASKED, NOT ASSUMED. When the composition mounts `ctx.userQuestions` — the harness's own
  *      blocking human channel, the same one plan-mode's exit uses — the question is PUT TO THE PERSON and
- *      only their selection is recorded; a caller-supplied answer cannot stand in for it, and a channel
- *      that cannot reach anyone ends the call without a decision (RM5503). Only a composition with no
- *      channel at all falls back to the relayed answer, which is the contract the other three gates have.
+ *      only their selection is recorded; a caller-supplied answer cannot stand in for it. A channel that
+ *      RESOLVES with an answer the gate does not recognise is a person's decision the gate cannot record
+ *      and it ends the call (RM5504). A channel that FAILS ends the call too (RM5503), naming the cause the
+ *      channel threw — and there the caller may take the relayed route deliberately, with `relay=true`,
+ *      which the result reports as `source: "relayed"` rather than as a person's own selection, so a
+ *      composition whose channel cannot deliver the question can still start a run. A failure that means
+ *      the question was cancelled, aborted, or timed out is never relayable. Only a composition with no
+ *      channel at all falls back to the relayed answer unconditionally, which is the contract the other
+ *      three gates have.
  *   3. THE GOAL CANNOT BE CREATED WITHOUT IT. `syncRunGoal` refuses to create a goal for a run whose
  *      approval record is absent, in EVERY branch that would create one — not only the "no goal yet"
  *      branch. That is the property `tests/run-start-approval.spec.ts` asserts, because a single