imprint-mcp 0.6.2 → 0.6.4

package/src/imprint/teach-state.ts

@@ -172,7 +172,18 @@ export function resolveWorkflowTriagedPath(
   if (!ws) return null;
 
   const explicitPath = resolveTeachStatePath(site, ws.triagedPath);
-  if (explicitPath) return explicitPath;
+  if (explicitPath) {
+    // Older/resumed runs could accidentally triage an already-triaged session,
+    // leaving state pointed at `*.triaged.triaged.json`. Prefer the original
+    // single-triaged sibling when it still exists: it contains the complete
+    // load-bearing request set, while the second pass may have filtered requests
+    // selected by the first pass.
+    const singleTriagedPath = explicitPath.replace(/(?:\.triaged){2,}\.json$/, '.triaged.json');
+    if (singleTriagedPath !== explicitPath && existsSync(singleTriagedPath)) {
+      return singleTriagedPath;
+    }
+    return explicitPath;
+  }
 
   if (!ws.completedSteps.includes('triage')) return null;
 
@@ -186,7 +197,20 @@ export function resolveWorkflowTriagedPath(
 export function toRelativeTeachStatePath(site: string, absPath: string): string {
   const localRelative = relativeToLocalSite(site, absPath);
   if (localRelative) return localRelative;
-  return `_external_/${pathBasename(absPath)}`;
+  // External artifacts are not copied under the site root. Persist their real
+  // absolute path so a later bounded resume can still resolve them; the former
+  // `_external_/<basename>` label looked portable but pointed at no actual file.
+  return pathResolve(absPath);
+}
+
+const TOOL_SCOPED_RESUME_STEPS = new Set<TeachStep>(['generate', 'compile-playbook', 'emit']);
+
+/** `--tool` scopes the atomic per-tool compile unit. Earlier phases operate on
+ * the recording as a whole, while register is site-level, so accepting the flag
+ * there would either ignore it or falsely claim the run was bounded. */
+export function validateToolScopedResumeStep(fromStep: TeachStep | undefined): string | null {
+  if (fromStep && TOOL_SCOPED_RESUME_STEPS.has(fromStep)) return null;
+  return 'error: --tool is only supported for bounded compile resumes starting at generate, compile-playbook, or emit';
 }
 
 export function buildTeachStateFromSession(
@@ -366,6 +390,7 @@ export function resolveStepStartTarget(
   site: string,
   state: TeachState,
   fromStep: TeachStep,
+  toolName?: string,
 ): { workflowKey: string; ws: WorkflowState } {
   // Exclude in-progress `_pending_*` placeholders: they never carry a candidate
   // and never reached far enough, so a stale one with a newer timestamp would
@@ -381,6 +406,19 @@ export function resolveStepStartTarget(
       ].join('\n'),
     );
   }
+  if (toolName) {
+    const target = entries.find(
+      ([workflowKey, ws]) => workflowKey === toolName || ws.candidate?.toolName === toolName,
+    );
+    if (!target) {
+      throw new Error(
+        `Cannot resume tool "${toolName}" for "${site}": it is not present in the persisted teach state.`,
+      );
+    }
+    const [workflowKey, ws] = target;
+    assertResumableAt(site, workflowKey, ws, fromStep);
+    return { workflowKey, ws };
+  }
   // Most-recently-updated resumable workflow — the run a developer just executed
   // and wants to resume a single phase of. Newly discovered orphan sessions can
   // have newer timestamps but only `record`/`redact`; they must not shadow the
@@ -423,6 +461,7 @@ export function selectMultiToolResumePlans(
   opts?: {
     noInteractive?: boolean;
     allTools?: boolean;
+    toolName?: string;
     plannedToolNames?: ReadonlySet<string>;
   },
 ): MultiToolResumeSelection {
@@ -445,6 +484,17 @@ export function selectMultiToolResumePlans(
     }
     plans.push({ workflowKey: key, candidate: ws.candidate, sharedContext: ws.sharedContext });
   }
+  if (opts?.toolName) {
+    const selected = plans.find(
+      (plan) => plan.workflowKey === opts.toolName || plan.candidate?.toolName === opts.toolName,
+    );
+    if (!selected) {
+      throw new Error(
+        `Cannot resume tool "${opts.toolName}": it is not resumable from "${fromStep}" in the selected recording.`,
+      );
+    }
+    return { plans: [selected], skipped };
+  }
   if (opts?.noInteractive && !opts.allTools && plans.length > 1) {
     const primary = plans.find((plan) => plan.candidate?.primary);
     const selected = primary ?? plans.find((plan) => plan.workflowKey === targetWorkflowKey);

package/src/imprint/teach.ts

@@ -150,6 +150,30 @@ export function hasDurableAuthState(
   return stored.cookies.length > 0 || (stored.storage?.length ?? 0) > 0;
 }
 
+export function resolvedArtifactCheckpointPath(
+  site: string,
+  _storedPath: string | undefined,
+  resolvedPath: string,
+): string {
+  // toRelative keeps managed artifacts site-relative and genuine external
+  // artifacts absolute, so both forms remain resolvable on the next resume.
+  return toRelative(site, resolvedPath);
+}
+
+export function selectCompileSessionArtifact(
+  resumedTriagedPath: string | null,
+  redactedPath: string | null,
+): { path: string | null; triaged: boolean } {
+  const derivedTriagedPath = redactedPath?.replace(/\.redacted\.json$/, '.triaged.json') ?? null;
+  const path =
+    (resumedTriagedPath && existsSync(resumedTriagedPath) ? resumedTriagedPath : null) ??
+    (derivedTriagedPath && existsSync(derivedTriagedPath) ? derivedTriagedPath : redactedPath);
+  return {
+    path,
+    triaged: path === resumedTriagedPath || path === derivedTriagedPath,
+  };
+}
+
 function fileSha256(path: string): string {
   return createHash('sha256').update(readFileSync(path)).digest('hex');
 }
@@ -205,6 +229,8 @@ interface TeachOptions {
   keepTest?: boolean;
   /** Non-interactive: compile every detected candidate instead of primary only. */
   allTools?: boolean;
+  /** Bounded resume: compile exactly one persisted candidate from the retained recording. */
+  tool?: string;
   /** Skip the replay-and-diff stage entirely. */
   skipReplay?: boolean;
   /** Run only specific phases of the teach chain. `fromStep` resumes a PRIOR run
@@ -490,6 +516,7 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
   let workflowKey: string | null = null;
   let sessionPath: string | null = opts.fromSession ?? null;
   let redactedPath: string | null = null;
+  let resumedTriagedPath: string | null = null;
   let usingFromSession = false;
 
   const hasExisting = completedWorkflows.length > 0 || incompleteWorkflows.length > 0;
@@ -506,7 +533,7 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
     // Non-interactive phase resume: start at a specific step, reusing a prior
     // run's persisted outputs. resolveStepStartTarget picks the most-recent
     // workflow and THROWS if it didn't reach far enough (the dependency guard).
-    const target = resolveStepStartTarget(site, state, opts.fromStep);
+    const target = resolveStepStartTarget(site, state, opts.fromStep, opts.tool);
     workflowKey = target.workflowKey;
     startFrom = opts.fromStep;
     sessionPath = resolveTeachStatePath(site, target.ws.sessionPath);
@@ -1215,9 +1242,14 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
     }
     const ws = state.workflows[workflowKey];
     const resolvedTriagedPath = resolveWorkflowTriagedPath(site, ws);
-    if (ws && resolvedTriagedPath && !ws.triagedPath) {
+    resumedTriagedPath = resolvedTriagedPath;
+    if (
+      ws &&
+      resolvedTriagedPath &&
+      resolveTeachStatePath(site, ws.triagedPath) !== resolvedTriagedPath
+    ) {
       updateCheckpoint(site, state, workflowKey, 'triage', {
-        triagedPath: toRelative(site, resolvedTriagedPath),
+        triagedPath: resolvedArtifactCheckpointPath(site, ws.triagedPath, resolvedTriagedPath),
       });
     }
     // A `--from-step` resume into plan-prereqs/generate reconstructs the prior
@@ -1242,6 +1274,7 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
       const selection = selectMultiToolResumePlans(state, workflowKey, startFrom, {
         noInteractive: opts.noInteractive,
         allTools: opts.allTools,
+        toolName: opts.tool,
         plannedToolNames,
       });
       for (const { workflowKey: skippedKey, reason } of selection.skipped) {
@@ -1325,15 +1358,12 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
   // thousands of irrelevant requests (large auth recordings otherwise may never converge on a
   // playbook because of this). The detect-candidates summary already triages;
   // this aligns the compile session with it.
-  const triagedCandidate = redactedPath?.replace(/\.redacted\.json$/, '.triaged.json');
-  const sessionForCompile =
-    triagedCandidate && existsSync(triagedCandidate) ? triagedCandidate : redactedPath;
-  const useTriaged = sessionForCompile === triagedCandidate;
-  const compileSessionPath = requireSessionFile(sessionForCompile, {
+  const compileSessionArtifact = selectCompileSessionArtifact(resumedTriagedPath, redactedPath);
+  const compileSessionPath = requireSessionFile(compileSessionArtifact.path, {
     site,
     workflowKey: plans[0]?.workflowKey ?? workflowKey,
     startFrom,
-    kind: useTriaged ? 'triaged' : 'redacted',
+    kind: compileSessionArtifact.triaged ? 'triaged' : 'redacted',
   });
 
   // ── Clean up stale tools from previous teach runs ──
@@ -1380,66 +1410,61 @@ export async function teach(opts: TeachOptions): Promise<TeachResult> {
   const authDetected = plans.some((pl) => sharedContextHasAuth(pl.sharedContext));
   let buildPlanPath = '';
   let sharedModulesManifest: SharedModuleManifestEntry[] = [];
-  if ((selectedCandidates.length >= 2 || authDetected) && willGenerate && compileModel) {
-    const sidecar = buildPlanSidecarPath(site);
-    const firstWs = state.workflows[plans[0]?.workflowKey ?? ''];
-    // Reuse the cached plan only when resuming PAST plan-prereqs (e.g. --from-step
-    // generate). When plan-prereqs is the explicit target (`--only plan-prereqs` /
-    // `--from-step plan-prereqs`), the user is asking to rebuild shared modules, so
-    // force a fresh planner run instead of short-circuiting to the cached sidecar.
-    const alreadyPlanned =
-      opts.fromStep !== 'plan-prereqs' &&
-      plans.every((pl) =>
-        state.workflows[pl.workflowKey]?.completedSteps.includes('plan-prereqs'),
-      ) &&
-      existsSync(sidecar);
-    if (alreadyPlanned && firstWs) {
-      // Resume past plan-prereqs — reuse the persisted plan + manifest.
-      buildPlanPath = sidecar;
-      sharedModulesManifest = firstWs.sharedModules ?? [];
-    } else {
-      // Mute raw `[imprint …]` logs from the planning subtree (build-plan,
-      // teach-plan, prereq-builder) while the spinner is live — progress flows
-      // through onProgress → spinner.message instead, matching the replay and
-      // compile phases. The skip/timeout reason is surfaced cleanly below.
-      muteLog();
-      spinner.start('Planning shared modules');
-      try {
-        const prereq = await planAndBuildPrereqs({
-          site,
-          redactedSessionPath: compileSessionPath,
-          candidates: selectedCandidates,
-          sharedContext: plans[0]?.sharedContext,
-          siteClassifications,
-          providerName: compileProviderName,
-          model: compileModel,
-          onProgress: (msg) => spinner.message(msg),
-        });
-        buildPlanPath = prereq.buildPlanPath;
-        sharedModulesManifest = prereq.sharedModules;
-        const verified = sharedModulesManifest.filter((m) => m.verified).length;
-        spinner.stop(
-          buildPlanPath
-            ? `Build plan ready (${verified}/${sharedModulesManifest.length} shared module${sharedModulesManifest.length === 1 ? '' : 's'} verified).`
-            : 'Build plan skipped.',
-        );
-        if (prereq.skippedReason) p.log.warn(prereq.skippedReason);
-      } catch (err) {
-        spinner.stop('Build planning failed — compiling tools independently.');
-        p.log.warn(
-          `Build planning failed: ${err instanceof Error ? err.message : String(err)}\nTools will compile without shared modules.`,
-        );
-        buildPlanPath = '';
-        sharedModulesManifest = [];
-      } finally {
-        unmuteLog();
-      }
-      for (const pl of plans) {
-        updateCheckpoint(site, state, pl.workflowKey, 'plan-prereqs', {
-          buildPlanPath: buildPlanPath ? toRelative(site, buildPlanPath) : undefined,
-          sharedModules: sharedModulesManifest,
-        });
-      }
+  const sidecar = buildPlanSidecarPath(site);
+  const firstWs = state.workflows[plans[0]?.workflowKey ?? ''];
+  // A bounded primary-only resume still belongs to its original multi-tool
+  // build plan. Reuse that durable contract even though this invocation selects
+  // one tool; otherwise its assigned shared modules and producer-token contract
+  // silently disappear from the revision agent's context.
+  const alreadyPlanned =
+    opts.fromStep !== 'plan-prereqs' &&
+    plans.every((pl) => state.workflows[pl.workflowKey]?.completedSteps.includes('plan-prereqs')) &&
+    existsSync(sidecar);
+  if (willGenerate && compileModel && alreadyPlanned && firstWs) {
+    buildPlanPath = sidecar;
+    sharedModulesManifest = firstWs.sharedModules ?? [];
+  } else if ((selectedCandidates.length >= 2 || authDetected) && willGenerate && compileModel) {
+    // Mute raw `[imprint …]` logs from the planning subtree (build-plan,
+    // teach-plan, prereq-builder) while the spinner is live — progress flows
+    // through onProgress → spinner.message instead, matching the replay and
+    // compile phases. The skip/timeout reason is surfaced cleanly below.
+    muteLog();
+    spinner.start('Planning shared modules');
+    try {
+      const prereq = await planAndBuildPrereqs({
+        site,
+        redactedSessionPath: compileSessionPath,
+        candidates: selectedCandidates,
+        sharedContext: plans[0]?.sharedContext,
+        siteClassifications,
+        providerName: compileProviderName,
+        model: compileModel,
+        onProgress: (msg) => spinner.message(msg),
+      });
+      buildPlanPath = prereq.buildPlanPath;
+      sharedModulesManifest = prereq.sharedModules;
+      const verified = sharedModulesManifest.filter((m) => m.verified).length;
+      spinner.stop(
+        buildPlanPath
+          ? `Build plan ready (${verified}/${sharedModulesManifest.length} shared module${sharedModulesManifest.length === 1 ? '' : 's'} verified).`
+          : 'Build plan skipped.',
+      );
+      if (prereq.skippedReason) p.log.warn(prereq.skippedReason);
+    } catch (err) {
+      spinner.stop('Build planning failed — compiling tools independently.');
+      p.log.warn(
+        `Build planning failed: ${err instanceof Error ? err.message : String(err)}\nTools will compile without shared modules.`,
+      );
+      buildPlanPath = '';
+      sharedModulesManifest = [];
+    } finally {
+      unmuteLog();
+    }
+    for (const pl of plans) {
+      updateCheckpoint(site, state, pl.workflowKey, 'plan-prereqs', {
+        buildPlanPath: buildPlanPath ? toRelative(site, buildPlanPath) : undefined,
+        sharedModules: sharedModulesManifest,
+      });
     }
   }