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

package/lib/errors.d.ts

@@ -133,6 +133,18 @@ export declare const TOOL_ERRORS: {
         readonly problem: "the run has unresolved delegated work, so this phase cannot lock yet";
         readonly next: "call recursive_status to see the pending delegation, have the child write its reply.md, then lock again";
     };
+    readonly RUN_START_NO_CHANNEL: {
+        readonly code: "RM5502";
+        readonly klass: "runtime";
+        readonly problem: "the run-start gate needs an answer, and this composition mounts no user-questions channel to ask one directly";
+        readonly next: string;
+    };
+    readonly RUN_START_UNANSWERED: {
+        readonly code: "RM5503";
+        readonly klass: "runtime";
+        readonly problem: "the user-questions channel mounted in this composition refused the run-start question, so no person was asked";
+        readonly next: string;
+    };
     readonly RUNTIME_REFUSED: {
         readonly code: "RM5501";
         readonly klass: "runtime";

package/lib/goals-projection.d.ts

@@ -81,12 +81,42 @@ export declare function isRunGoal(goal: GoalViewLike | undefined, runId: string)
  * Sync a run's durable goal to the requested phase. Safe: never touches a goal
  * whose objective is not this run's marker, and never re-creates over a
  * non-complete foreign goal.
+ *
+ * ⚠ `approved` IS THE PHASE-0 GATE, and it defaults to the SAFE direction. A goal is not a label:
+ * `create` returns an ARMED view and the harness starts driving autonomous goal rounds for the
+ * session, so creating one is starting the run. The owner's rule is that phase 0 requires explicit
+ * approval, which means the projection must be unable to arm anything on its own — hence a default of
+ * `false` and an explicit refusal in EVERY branch that would call `create`, including the two
+ * replace-a-completed-goal branches (an unapproved run cannot have reached `complete`, but "cannot
+ * happen" is what the single unguarded branch relied on too).
+ *
+ * ⚠ AND IT IS REACHED ON ORDINARY WORK, so the unapproved path is QUIET AND IDEMPOTENT: no goal is
+ * created, nothing is written, no error is thrown, and the run's artifacts are untouched. The caller
+ * reads {@link RUN_START_NOT_APPROVED} to tell "this run has not been started yet" apart from a real
+ * failure, so a normal phase step never surfaces a warning.
+ *
+ * `approved` is passed IN rather than read here because this module is pure: it takes the goal service
+ * seam and nothing else, and the plugin's own filesystem reads live in the runtime (see
+ * `RecursiveRuntime.readRunStartApproval`).
+ */
+export declare function syncRunGoal(service: GoalServiceLike | undefined | null, agent: AgentHandle, runId: string, runState: RunState, approved?: boolean): SyncResult;
+/**
+ * Block the current run goal (used on a gate-block). Never touches a foreign goal.
+ *
+ * ⚠ A RUN THAT WAS NEVER STARTED HAS NO GOAL TO BLOCK, so this reports the unapproved state in the
+ * same words as {@link syncRunGoal} rather than "no current goal to block": the caller's question is
+ * "why is there no goal", and the answer must not depend on which entry point happened to ask.
  */
-export declare function syncRunGoal(service: GoalServiceLike | undefined | null, agent: AgentHandle, runId: string, runState: RunState): SyncResult;
-/** Block the current run goal (used on a gate-block). Never touches a foreign goal. */
 export declare function blockRunGoal(service: GoalServiceLike | undefined | null, agent: AgentHandle, runId: string, reason: {
     code: string;
     message: string;
 }): SyncResult;
-/** Bridge a run's blocked goal back to active (used on a reopen). */
-export declare function resumeRunGoal(service: GoalServiceLike | undefined | null, agent: AgentHandle, runId: string): SyncResult;
+/**
+ * Bridge a run's blocked goal back to active (used on a reopen).
+ *
+ * ⚠ REOPEN IS NOT A BACK DOOR TO STARTING A RUN. It routes through {@link syncRunGoal}, so a reopen of
+ * an unapproved run cannot create the goal that init deliberately withheld. An APPROVED run is
+ * unaffected: its approval outlives the reopen, because the approval is a durable line in the run's
+ * own Phase 0 artifact rather than a value held in memory (verified in `tests/run-start-approval.spec.ts`).
+ */
+export declare function resumeRunGoal(service: GoalServiceLike | undefined | null, agent: AgentHandle, runId: string, approved?: boolean): SyncResult;