@veewo/claw 0.1.93 → 0.1.95

package/README.md

@@ -35,6 +35,8 @@ claw plan create "Ephemeral harness" --scope session --goal "Use plan and Goal w
 
 `claw plan create` uses explicit `--template` first, otherwise the project's configured `defaultPlanTemplate`, and finally falls back to the built-in `default` template. You can select a template explicitly with `claw plan create "<title>" --template <name>` or `claw plan create --template <name> --title "<title>"`.
 
+New project tasks are grouped under `.claw/tasks/YYYY-MM-DD/`. On the first `claw context` call of each local calendar day, claw performs a lock-protected maintenance pass: it clears `.claw/runtime/tmp/` (and removes legacy `.claw/tmp/`), moves date-scoped task folders from before yesterday into the archive even when old plans have no `completedAt`, archives legacy flat tasks by `plan.updatedAt` (falling back to the plan file timestamp), applies `maxTasksToKeep` to archived tasks, removes bindings to plans no longer under active tasks, and sweeps expired session workflows. This is lazy maintenance, not a background scheduler.
+
 `--scope session` stores the workflow in a user-level directory keyed by the platform session id, so it works without a project `.claw` directory and recovers across cwd changes. It preserves plan/task/subplan/Goal behavior while disabling project knowledge capture, memory/GitNexus refresh, and project retention. Use `claw session clean` for the current session or `claw session clean --expired` for the seven-day TTL sweep.
 
 Projects can add reusable templates directly under `.claw/templates` with `.json`, `.js`, `.mjs`, or `.cjs` files. Put `defaultPlanTemplate` in `.claw/project.json` for a shared team default, or in `.claw/project-override.json` for a local personal override.

package/dist/bin.js

@@ -9,11 +9,23 @@ process.emitWarning = ((warning, ...args) => {
 });
 void main();
 async function main() {
-    if (!await shouldLoadCliForInvocation(process.argv.slice(2), process.cwd(), process.env)) {
+    const args = process.argv.slice(2);
+    if (!await shouldLoadCliForInvocation(args, process.cwd(), process.env)) {
+        return;
+    }
+    if (isSearchInvocation(args)) {
+        const { runSearchEntry } = await import("./search-entry.js");
+        await runSearchEntry(args.slice(1));
         return;
     }
     await import("./cli.js");
 }
+function isSearchInvocation(args) {
+    return args[0] === "search"
+        && args[1] !== "help"
+        && !args.includes("--help")
+        && !args.includes("-h");
+}
 function shouldSuppressSqliteExperimentalWarning(warning, args) {
     const message = typeof warning === "string"
         ? warning

package/dist/bin.js.map

@@ -1 +1 @@
-{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAE3E,MAAM,mBAAmB,GAAG,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAE9D,OAAO,CAAC,WAAW,GAAG,CAAC,CAAC,OAAgB,EAAE,GAAG,IAAe,EAAE,EAAE;IAC9D,IAAI,uCAAuC,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC;QAC3D,OAAO;IACT,CAAC;IACD,OAAO,mBAAmB,CAAC,OAAgB,EAAE,GAAI,IAAW,CAAC,CAAC;AAChE,CAAC,CAA+B,CAAC;AAEjC,KAAK,IAAI,EAAE,CAAC;AAEZ,KAAK,UAAU,IAAI;IACjB,IAAI,CAAC,MAAM,0BAA0B,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACzF,OAAO;IACT,CAAC;IACD,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;AAC3B,CAAC;AAED,SAAS,uCAAuC,CAAC,OAAgB,EAAE,IAAe;IAChF,MAAM,OAAO,GACX,OAAO,OAAO,KAAK,QAAQ;QACzB,CAAC,CAAC,OAAO;QACT,CAAC,CAAC,OAAO,YAAY,KAAK;YACxB,CAAC,CAAC,OAAO,CAAC,OAAO;YACjB,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACxB,MAAM,IAAI,GACR,OAAO,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ;QACzB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACT,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,OAAO,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ,IAAI,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC;YAC3D,CAAC,CAAC,MAAM,CAAE,IAAI,CAAC,CAAC,CAAwB,CAAC,IAAI,IAAI,EAAE,CAAC;YACpD,CAAC,CAAC,OAAO,YAAY,KAAK;gBACxB,CAAC,CAAC,OAAO,CAAC,IAAI;gBACd,CAAC,CAAC,EAAE,CAAC;IAEb,OAAO,IAAI,KAAK,qBAAqB,IAAI,OAAO,CAAC,QAAQ,CAAC,mCAAmC,CAAC,CAAC;AACjG,CAAC"}
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAE3E,MAAM,mBAAmB,GAAG,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAE9D,OAAO,CAAC,WAAW,GAAG,CAAC,CAAC,OAAgB,EAAE,GAAG,IAAe,EAAE,EAAE;IAC9D,IAAI,uCAAuC,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC;QAC3D,OAAO;IACT,CAAC;IACD,OAAO,mBAAmB,CAAC,OAAgB,EAAE,GAAI,IAAW,CAAC,CAAC;AAChE,CAAC,CAA+B,CAAC;AAEjC,KAAK,IAAI,EAAE,CAAC;AAEZ,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,IAAI,CAAC,MAAM,0BAA0B,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACxE,OAAO;IACT,CAAC;IACD,IAAI,kBAAkB,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7B,MAAM,EAAE,cAAc,EAAE,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAAC,CAAC;QAC7D,MAAM,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACpC,OAAO;IACT,CAAC;IACD,MAAM,MAAM,CAAC,UAAU,CAAC,CAAC;AAC3B,CAAC;AAED,SAAS,kBAAkB,CAAC,IAAc;IACxC,OAAO,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ;WACtB,IAAI,CAAC,CAAC,CAAC,KAAK,MAAM;WAClB,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC;WACxB,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED,SAAS,uCAAuC,CAAC,OAAgB,EAAE,IAAe;IAChF,MAAM,OAAO,GACX,OAAO,OAAO,KAAK,QAAQ;QACzB,CAAC,CAAC,OAAO;QACT,CAAC,CAAC,OAAO,YAAY,KAAK;YACxB,CAAC,CAAC,OAAO,CAAC,OAAO;YACjB,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACxB,MAAM,IAAI,GACR,OAAO,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ;QACzB,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QACT,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,OAAO,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ,IAAI,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC;YAC3D,CAAC,CAAC,MAAM,CAAE,IAAI,CAAC,CAAC,CAAwB,CAAC,IAAI,IAAI,EAAE,CAAC;YACpD,CAAC,CAAC,OAAO,YAAY,KAAK;gBACxB,CAAC,CAAC,OAAO,CAAC,IAAI;gBACd,CAAC,CAAC,EAAE,CAAC;IAEb,OAAO,IAAI,KAAK,qBAAqB,IAAI,OAAO,CAAC,QAAQ,CAAC,mCAAmC,CAAC,CAAC;AACjG,CAAC"}

package/dist/cli.js

@@ -5,21 +5,20 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { createHash } from "node:crypto";
 import { spawn, spawnSync } from "node:child_process";
-import { buildDirectWorkflowGuidance, DEFAULT_MAX_TASKS_TO_KEEP, checkProjectProtocol, ClawError, buildPlanWorkflowGuidance, buildMemoryIndex, buildSessionStartDefaultPrompt, buildSessionStartRecoveredPrompt, editPlan, ensureProjectProtocol, enforceTaskRetention, ingestTruth, initProject, getTemplateTaskDoneChoices, resolvePlanTemplateFile, resolveProjectContext, resolveWorkflowProjectContext, resolveSessionWorkflowContext, deleteSessionWorkflow, sweepExpiredSessionWorkflows, resolveSessionBoundPlan, resolveContext, resolveSeedPlanTemplate, searchMemory, warmProjectMemoryEmbedding, showPlan, createSubplan, switchTask, tryCaptureKnowledgeStop, claimKnowledgeFinalizationJob, changedKnowledgeMarkdownPaths, listRetryableKnowledgeFinalizationJobs, governChangedKnowledgeMarkdown, normalizeTruthMarkdownEncoding, recordKnowledgeFinalizationResult, snapshotKnowledgeMarkdown, writeKnowledgeFinalizationJob, unbindSession, writePlan, } from "@veewo/claw-core";
+import { buildDirectWorkflowGuidance, DEFAULT_MAX_TASKS_TO_KEEP, checkProjectProtocol, ClawError, buildPlanWorkflowGuidance, buildMemoryIndex, buildSessionStartDefaultPrompt, buildSessionStartRecoveredPrompt, editPlan, ensureProjectProtocol, enforceTaskRetention, findTaskDirectory, runDailyMaintenance, ingestTruth, initProject, getTemplateTaskDoneChoices, resolvePlanTemplateFile, resolveProjectContext, resolveWorkflowProjectContext, resolveSessionWorkflowContext, deleteSessionWorkflow, sweepExpiredSessionWorkflows, resolveSessionBoundPlan, resolveContext, resolveSeedPlanTemplate, searchMemoryAsync, warmProjectMemoryEmbedding, showPlan, createSubplan, switchTask, tryCaptureKnowledgeStop, claimKnowledgeFinalizationJob, changedKnowledgeMarkdownPaths, listRetryableKnowledgeFinalizationJobs, governChangedKnowledgeMarkdown, normalizeTruthMarkdownEncoding, recordKnowledgeFinalizationResult, snapshotKnowledgeMarkdown, writeKnowledgeFinalizationJob, unbindSession, writePlan, } from "@veewo/claw-core";
 import { buildCodexDriverEnvelope } from "./codex-driver.js";
 import { checkCodexRuntime, resolveCodexSdkEntryPath } from "./codex-runtime.js";
 import { extractLatestFinalAssistantMessage, extractTaskDoneConclusions, } from "./codex-transcript.js";
 import { consumeBufferedHookInput } from "./knowledge-hook-preflight.js";
 import { resolveInvocationHost, withoutInvocationHost } from "./invocation-host.js";
 import { runOpencodeKnowledgeWriter } from "./opencode-runner.js";
-import { captureKnowledgeGitState, commitKnowledgeDocumentation } from "./knowledge-git-commit.js";
 const CLI_VERSION = readCliVersion();
 const TOP_LEVEL_COMMANDS = [
     { name: "init [options]", summary: "Initialize and normalize the .claw project surface." },
     { name: "context [--task <name>]", summary: "Resolve project context, auto-initializing or correcting .claw state." },
     { name: "session clean [--expired]", summary: "Remove current or expired session workflow state." },
     { name: "check", summary: "Check and auto-correct .claw project protocol fields." },
-    { name: "plan <subcommand> [options]", summary: "Plan lifecycle: create, start, edit, remove, wait, resume, show, done." },
+    { name: "plan <subcommand> [options]", summary: "Plan lifecycle: create, start, edit, remove, wait, resume, sync, show, done." },
     { name: "codex driver", summary: "Return the versioned code-mode driver used by the Codex adapter." },
     { name: "template <subcommand> [options]", summary: "Plan template helpers such as validation." },
     { name: "task <subcommand> [options]", summary: "Task lifecycle helpers inside an existing plan." },
@@ -93,6 +92,10 @@ const COMMAND_HELP = {
                     { flag: "--summary <text>", detail: "Set the plan summary." },
                     { flag: "--rule <text>", detail: "Append a rule (repeatable)." },
                     { flag: "--key-decision <text>", detail: "Append a key decision (repeatable)." },
+                    { flag: "--retrospective <text>", detail: "Set the retrospective summary; required before --status end.completed." },
+                    { flag: "--what-worked <text>", detail: "Append a retrospective success (repeatable)." },
+                    { flag: "--issue <text>", detail: "Append a retrospective issue (repeatable)." },
+                    { flag: "--follow-up <text>", detail: "Append a retrospective follow-up (repeatable)." },
                     { flag: "--reference <path>", detail: "Add a reference; follow it immediately with --why (repeatable)." },
                     { flag: "--why <text>", detail: "Explain the immediately preceding --reference." },
                     { flag: "--task-name <name>", detail: "Advanced: override the session-bound task scope." },
@@ -131,6 +134,11 @@ const COMMAND_HELP = {
                     { flag: "--plan-file <relative-path>", detail: "Advanced: override the session-bound plan file." },
                 ],
             },
+            sync: {
+                usage: ["{script} plan sync"],
+                description: "Resynchronize a recovered active Codex plan with host progress and Goal Mode without mutating the plan.",
+                summary: "Resync a recovered active Codex plan.",
+            },
             start: {
                 usage: ["{script} plan start --requirements <text> --add-task <title> [--detail <text>] [options]"],
                 description: "Atomically apply refined plan content, append outcome tasks, and execute the current template task's plan-start guidance in one serialized mutation.",
@@ -161,8 +169,8 @@ const COMMAND_HELP = {
             },
             done: {
                 usage: ["{script} plan done --retrospective <text> [options]"],
-                description: "Close out a plan: write a retrospective, mark status end.completed with completedAt, retain it for at least one hour, sweep older completed tasks into the archive, and queue the async completion refresh.",
-                summary: "Close out a plan with a retrospective and queue completion refresh.",
+                description: "Shortcut for applying closeout fields and --status end.completed in one ordered plan edit; it retains the task for at least one hour, sweeps older completed tasks into the archive, and queues the async completion refresh.",
+                summary: "Shortcut for completing a plan with a retrospective and queueing completion refresh.",
                 options: [
                     { flag: "--retrospective <text>", detail: "Retrospective summary (required)." },
                     { flag: "--key-decision <text>", detail: "Append a durable key decision when one exists (repeatable)." },
@@ -443,7 +451,7 @@ async function main() {
                 }));
                 return;
             case "search":
-                runSearch(args);
+                await runSearch(args);
                 return;
             case "direct":
                 runDirect(args, effectiveHost);
@@ -541,15 +549,21 @@ async function runPlan(args, effectiveHost) {
             if (operations.length === 0) {
                 throw new ClawError("PROJECT_CONFIG_INVALID", "plan edit requires at least one plan field or --status.");
             }
+            const ownerSessionKey = resolveOwnerSessionKey() ?? undefined;
+            const entersEndState = requestsPlanEndState(operations);
+            const queuePlanEndFinalization = entersEndState
+                ? preparePlanEndFinalization(process.cwd(), ownerSessionKey)
+                : undefined;
             const result = await editPlan({
                 cwd: process.cwd(),
                 ...target,
                 operations,
                 commandSource: "plan.edit",
                 host: effectiveHost,
-                ownerSessionKey: resolveOwnerSessionKey() ?? undefined,
+                ownerSessionKey,
             });
-            printJson(compactPlanCommandResult("plan.edit", result, effectiveHost));
+            const completionRefresh = queuePlanEndFinalization?.(result.taskName);
+            printJson(compactPlanCommandResult("plan.edit", result, effectiveHost, completionRefresh));
             if (result.operationChain?.status === "partial")
                 process.exitCode = 1;
             return;
@@ -578,6 +592,9 @@ async function runPlan(args, effectiveHost) {
         case "resume":
             await runPlanStatusAlias(args, "process.active", "plan.resume", effectiveHost);
             return;
+        case "sync":
+            await runPlanSync(args, effectiveHost);
+            return;
         case "start": {
             const updates = readPlanFieldUpdates(args);
             const appendTasks = readExplicitAddedTasks(args);
@@ -614,26 +631,16 @@ async function runPlan(args, effectiveHost) {
             const target = readPlanMutationTarget(args);
             assertNoRemainingArgs(args, "plan done");
             const ownerSessionKey = resolveOwnerSessionKey() ?? undefined;
-            const workflowProject = resolveWorkflowProjectContext(process.cwd(), ownerSessionKey);
-            const gitNexusPreflightAnalyzed = workflowProject.scope === "project"
-                ? ensureGitNexusReadyForPlanDone(process.cwd())
-                : false;
+            const queuePlanEndFinalization = preparePlanEndFinalization(process.cwd(), ownerSessionKey);
             const result = await editPlan({
                 cwd: process.cwd(),
                 ...target,
-                updates,
-                planStatus: "end.completed",
+                operations: planCompletionOperations(updates),
                 commandSource: "plan.done",
                 host: effectiveHost,
                 ownerSessionKey,
             });
-            const completionRefresh = workflowProject.scope === "project"
-                ? queueCompletionRefresh({
-                    cwd: process.cwd(),
-                    taskName: result.taskName,
-                    skipGitNexusRefresh: gitNexusPreflightAnalyzed,
-                })
-                : undefined;
+            const completionRefresh = queuePlanEndFinalization?.(result.taskName);
             printJson(compactPlanCommandResult("plan.done", result, effectiveHost, completionRefresh));
             return;
         }
@@ -671,7 +678,28 @@ async function runPlanStatusAlias(args, planStatus, command, effectiveHost) {
         ownerSessionKey: resolveOwnerSessionKey() ?? undefined,
     });
     assertNoRemainingArgs(args, command);
-    printJson(compactPlanCommandResult(command, result, effectiveHost));
+    printJson(compactPlanCommandResult(command, result, effectiveHost, undefined, true));
+}
+async function runPlanSync(args, effectiveHost) {
+    const ownerSessionKey = resolveOwnerSessionKey() ?? undefined;
+    const result = showPlan({ cwd: process.cwd(), ...readPlanMutationTarget(args), ownerSessionKey });
+    assertNoRemainingArgs(args, "plan sync");
+    if (result.plan.status !== "process.active") {
+        printJson({ ok: true, command: "plan.sync", planPath: result.planPath, planStatus: result.plan.status });
+        return;
+    }
+    const project = resolveWorkflowProjectContext(process.cwd(), ownerSessionKey);
+    const workflowGuidance = await buildPlanWorkflowGuidance({
+        taskName: result.taskName,
+        planFile: result.planFile,
+        plan: result.plan,
+        projectRoot: project.projectRoot,
+        projectConfig: project.projectConfig,
+        previousStatus: "process.wait",
+        host: effectiveHost,
+        recoveryResync: true,
+    });
+    printJson(compactPlanCommandResult("plan.sync", { ...result, planStatus: result.plan.status, workflowGuidance }, effectiveHost, undefined, true));
 }
 async function runTemplate(args) {
     const subcommand = args.shift();
@@ -790,7 +818,7 @@ async function runTask(args, effectiveHost) {
             throw new ClawError("PROJECT_CONFIG_INVALID", `Unknown task subcommand "${subcommand ?? ""}".`);
     }
 }
-function runSearch(args) {
+async function runSearch(args) {
     const subcommand = args[0];
     if (subcommand === "index") {
         args.shift();
@@ -815,7 +843,7 @@ function runSearch(args) {
     printJson({
         ok: true,
         command: "search",
-        ...searchMemory({
+        ...await searchMemoryAsync({
             cwd: process.cwd(),
             limit: readOptionalNumber(args, "--limit"),
             query: readRequiredSearchQuery(args),
@@ -844,6 +872,7 @@ async function runContextCommand(args, cwd = process.cwd(), ownerSessionKey = re
     let fixedPaths = [];
     const sessionProject = resolveSessionWorkflowContext(ownerSessionKey ?? undefined);
     if (sessionProject) {
+        const maintenance = runDailyMaintenance(sessionProject, { excludeSessionKey: ownerSessionKey ?? undefined, includeProject: false });
         const activeWorkflow = !taskName && ownerSessionKey
             ? await tryResolveActiveWorkflowSnapshot(cwd, ownerSessionKey, effectiveHost)
             : null;
@@ -854,6 +883,7 @@ async function runContextCommand(args, cwd = process.cwd(), ownerSessionKey = re
         return {
             project: sessionProject,
             ...(activeWorkflow ? { activeWorkflow } : {}),
+            ...(maintenance.ran ? { maintenance } : {}),
             ...(codexRuntimeError ? { error: codexRuntimeError } : {}),
         };
     }
@@ -869,6 +899,7 @@ async function runContextCommand(args, cwd = process.cwd(), ownerSessionKey = re
         initProject({ cwd, version: CLI_VERSION });
         initialized = true;
     }
+    const maintenance = runDailyMaintenance(resolveProjectContext(cwd), { excludeSessionKey: ownerSessionKey ?? undefined });
     let resolved = resolveContext(cwd, taskName);
     const versionSync = syncProjectVersionWithCli(cwd, resolved.project);
     if (versionSync.projectVersionUpdated) {
@@ -888,6 +919,7 @@ async function runContextCommand(args, cwd = process.cwd(), ownerSessionKey = re
     launchProjectEmbeddingWarmup(resolved.project);
     return {
         ...resolved,
+        ...(maintenance.ran ? { maintenance } : {}),
         ...(activeWorkflow ? { activeWorkflow } : {}),
         ...(codexRuntimeError ? { error: codexRuntimeError } : {}),
         protocolCheck: checkProjectProtocol(cwd),
@@ -1221,10 +1253,6 @@ async function runInternalKnowledgeFinalize(args) {
         const project = resolveProjectContext(running.projectRoot);
         const useBuiltInAutomation = usesBuiltInKnowledgeWriter(running);
         const knowledgeBefore = snapshotKnowledgeMarkdown(project.truthDir);
-        const autoCommitKnowledge = project.projectConfig?.autoCommitKnowledge !== false;
-        const knowledgeGitState = autoCommitKnowledge
-            ? captureKnowledgeGitState(running.projectRoot, project.truthDir)
-            : null;
         const writerRun = await runKnowledgeWriterForJob(running);
         const knowledgeGovernance = useBuiltInAutomation
             ? governChangedKnowledgeMarkdown({
@@ -1268,14 +1296,6 @@ async function runInternalKnowledgeFinalize(args) {
             ...(knowledgeGovernance ? { knowledgeGovernance } : {}),
             truthEncoding,
         });
-        if (autoCommitKnowledge) {
-            commitKnowledgeDocumentation({
-                state: knowledgeGitState,
-                truthDir: project.truthDir,
-                changedPaths: changedKnowledgePaths,
-                message: running.taskName,
-            });
-        }
     }
     catch (error) {
         const failed = {
@@ -1477,7 +1497,7 @@ async function runSessionStartHook(effectiveHost) {
                 }
             }
         }
-        const additionalContext = buildSessionStartAdditionalContext(context, hookCwd);
+        const additionalContext = buildSessionStartAdditionalContext(context, hookCwd, effectiveHost);
         if (!additionalContext) {
             return;
         }
@@ -1557,14 +1577,18 @@ function safeResolveTempDir() {
         return null;
     }
 }
-function buildSessionStartAdditionalContext(context, sessionCwd) {
+function buildSessionStartAdditionalContext(context, sessionCwd, effectiveHost) {
     const versionSyncPrompt = buildVersionSyncPrompt(context);
     const searchGuidance = buildContextSearchGuidance(context);
     const runtimeErrorPrompt = buildCodexRuntimeErrorPrompt(context);
     const activeWorkflow = context.activeWorkflow;
     if (activeWorkflow) {
         const prompt = buildRecoveredWorkflowAdditionalContext(activeWorkflow, versionSyncPrompt);
-        const promptWithSearch = searchGuidance ? `${prompt}\n${searchGuidance}` : prompt;
+        const recoverySyncPrompt = effectiveHost === "codex" && activeWorkflow.planStatus === "process.active"
+            ? "Before continuing, run `claw plan sync` once through the fixed Codex driver to restore host progress and Goal Mode."
+            : "";
+        const promptWithSync = recoverySyncPrompt ? `${prompt}\n${recoverySyncPrompt}` : prompt;
+        const promptWithSearch = searchGuidance ? `${promptWithSync}\n${searchGuidance}` : promptWithSync;
         return runtimeErrorPrompt ? `${runtimeErrorPrompt}\n\n${promptWithSearch}` : promptWithSearch;
     }
     const project = context.project;
@@ -1731,18 +1755,15 @@ async function tryResolveActiveWorkflowSnapshot(cwd, ownerSessionKey, effectiveH
         return null;
     }
     try {
-        const relativePlanPath = path.relative(project.tasksDir, planPath);
-        const segments = relativePlanPath.split(path.sep);
-        const taskName = segments.shift();
-        const planFile = segments.join("/");
-        if (!taskName || !planFile) {
+        const target = parseTaskPlanPath(project, planPath);
+        if (!target) {
             unbindSession(project, ownerSessionKey);
             return null;
         }
         const result = showPlan({
             cwd,
-            taskName,
-            planFile,
+            taskName: target.taskName,
+            planFile: target.planFile,
             ownerSessionKey,
         });
         if (result.plan.status.startsWith("end.")) {
@@ -1859,16 +1880,15 @@ function readJson(filePath) {
 function stripBom(content) {
     return content.charCodeAt(0) === 0xfeff ? content.slice(1) : content;
 }
-function compactPlanCommandResult(command, result, effectiveHost, completionRefresh) {
+function compactPlanCommandResult(command, result, effectiveHost, completionRefresh, forceProjectionSync = false) {
     const archivedPlanPath = completionRefresh?.taskRetention.archivedCurrentTask?.taskName === result.taskName &&
         completionRefresh.taskRetention.archivedCurrentTask.archivedPlanPath
         ? completionRefresh.taskRetention.archivedCurrentTask.archivedPlanPath
         : undefined;
     const resolvedPlanPath = archivedPlanPath ?? result.planPath;
     const codexResult = effectiveHost === "codex";
-    const hostActions = codexResult ? buildHostActions(result) : [];
+    const hostActions = codexResult ? buildHostActions(result, { forceProjectionSync, actionIdPrefix: command === "plan.sync" ? `plan.sync:${createHash("sha256").update(result.planPath).digest("hex").slice(0, 16)}` : undefined }) : [];
     const nextsteps = codexResult
-        && command === "plan.done"
         && result.planStatus === "end.completed"
         && result.workflowGuidance.goalTool?.tool === "update_goal"
         && result.workflowGuidance.goalTool.status === "complete"
@@ -1878,7 +1898,7 @@ function compactPlanCommandResult(command, result, effectiveHost, completionRefr
     const includePlan = Boolean((command === "plan.create" || command === "subplan.create")
         && result.plan
         && (!codexResult || result.workflowGuidance.stage === "discussion"));
-    const achievement = command === "plan.done" && result.planStatus === "end.completed" && result.plan
+    const achievement = result.planStatus === "end.completed" && result.plan
         ? {
             status: result.planStatus,
             title: result.plan.title,
@@ -1902,7 +1922,7 @@ function compactPlanCommandResult(command, result, effectiveHost, completionRefr
         ...(!codexResult && result.changedTaskIds?.length ? { changedTaskIds: result.changedTaskIds } : {}),
         ...(!codexResult && result.appendedTaskIds?.length ? { appendedTaskIds: result.appendedTaskIds } : {}),
         ...(codexResult ? { stage: result.workflowGuidance.stage } : {}),
-        ...(!codexResult || command === "plan.done"
+        ...(!codexResult || result.planStatus === "end.completed"
             ? { nextsteps }
             : {}),
         ...(result.workflowGuidance.nextTask ? { nextTask: result.workflowGuidance.nextTask } : {}),
@@ -1937,9 +1957,10 @@ function compactPlanCommandResult(command, result, effectiveHost, completionRefr
         ...(!codexResult || !includePlan ? { planSummary } : {}),
     };
 }
-function buildHostActions(result) {
+function buildHostActions(result, options = {}) {
     const latestEvent = result.events?.at(-1);
-    if (!latestEvent) {
+    const actionIdPrefix = options.actionIdPrefix ?? latestEvent?.mutationId;
+    if (!actionIdPrefix) {
         return [];
     }
     const actions = [];
@@ -1950,18 +1971,20 @@ function buildHostActions(result) {
     if (isSubplanGoalHandoff && goalTool?.tool === "update_goal") {
         actions.push({
             schemaVersion: 1,
-            id: `${latestEvent.mutationId}:update_goal`,
+            id: `${actionIdPrefix}:update_goal`,
             tool: "update_goal",
             input: {
                 status: "complete",
             },
         });
     }
-    if (result.plan && codexPlanProjectionChanged(result.previousPlan, result.plan, result.planStatus)) {
+    if (result.plan
+        && result.plan.tasks.length > 0
+        && (options.forceProjectionSync || codexPlanProjectionChanged(result.previousPlan, result.plan, result.planStatus))) {
         const plan = buildCodexPlanProjection(result.plan, result.planStatus);
         actions.push({
             schemaVersion: 1,
-            id: `${latestEvent.mutationId}:update_plan`,
+            id: `${actionIdPrefix}:update_plan`,
             tool: "update_plan",
             input: {
                 explanation: result.workflowGuidance.summary,
@@ -1973,7 +1996,7 @@ function buildHostActions(result) {
         if (goalTool.tool === "create_goal") {
             actions.push({
                 schemaVersion: 1,
-                id: `${latestEvent.mutationId}:create_goal`,
+                id: `${actionIdPrefix}:create_goal`,
                 tool: "create_goal",
                 input: {
                     objective: goalTool.objective,
@@ -1986,7 +2009,7 @@ function buildHostActions(result) {
                 : goalTool.status;
             actions.push({
                 schemaVersion: 1,
-                id: `${latestEvent.mutationId}:update_goal`,
+                id: `${actionIdPrefix}:update_goal`,
                 tool: "update_goal",
                 input: {
                     status: codexStatus,
@@ -2003,12 +2026,13 @@ function codexPlanProjectionChanged(previousPlan, plan, planStatus) {
         !== JSON.stringify(buildCodexPlanProjection(plan, planStatus));
 }
 function buildCodexPlanProjection(plan, planStatus) {
-    let assignedInProgress = false;
+    const activeTask = plan.tasks.find((task) => task.status === "in_progress" || task.status === "subagent_running") ?? (planStatus === "process.active"
+        ? plan.tasks.find((task) => task.status !== "done")
+        : undefined);
     return plan.tasks.map((task) => {
         let status = task.status === "done" ? "completed" : "pending";
-        if (!assignedInProgress && planStatus === "process.active" && task.status !== "done") {
+        if (task.id === activeTask?.id) {
             status = "in_progress";
-            assignedInProgress = true;
         }
         return { step: task.title, status };
     });
@@ -2070,6 +2094,18 @@ function readOrderedPlanEditOperations(args) {
             case "--key-decision":
                 operations.push({ type: "plan.update", updates: { keyDecisions: [readChainValue(args, flag)] } });
                 break;
+            case "--retrospective":
+                operations.push({ type: "plan.update", updates: { retrospectiveSummary: readChainValue(args, flag) } });
+                break;
+            case "--what-worked":
+                operations.push({ type: "plan.update", updates: { whatWorked: [readChainValue(args, flag)] } });
+                break;
+            case "--issue":
+                operations.push({ type: "plan.update", updates: { issues: [readChainValue(args, flag)] } });
+                break;
+            case "--follow-up":
+                operations.push({ type: "plan.update", updates: { followUps: [readChainValue(args, flag)] } });
+                break;
             case "--reference": {
                 const path = readChainValue(args, flag);
                 const whyFlag = args.shift();
@@ -2088,6 +2124,15 @@ function readOrderedPlanEditOperations(args) {
     }
     return operations;
 }
+function requestsPlanEndState(operations) {
+    return operations.some((operation) => operation.type === "plan.status" && operation.status.startsWith("end."));
+}
+function planCompletionOperations(updates) {
+    return [
+        { type: "plan.update", updates },
+        { type: "plan.status", status: "end.completed" },
+    ];
+}
 function readOrderedTaskAddOperations(args) {
     const operations = [];
     while (args.length > 0) {
@@ -2222,16 +2267,25 @@ function readPlanMutationTarget(args) {
     if (!boundPlanPath) {
         throw new ClawError("PROJECT_CONFIG_INVALID", "No plan is bound to the current session. Create or recover a plan first, or use --task-name and optional --plan-file as an advanced override.");
     }
-    const relativePlanPath = path.relative(project.tasksDir, boundPlanPath);
-    const segments = relativePlanPath.split(path.sep).filter(Boolean);
-    if (segments.length < 2 || relativePlanPath.startsWith("..") || path.isAbsolute(relativePlanPath)) {
+    const target = parseTaskPlanPath(project, boundPlanPath);
+    if (!target) {
         throw new ClawError("PROJECT_CONFIG_INVALID", `Invalid session-bound plan path: ${boundPlanPath}`);
     }
     return {
-        taskName: segments[0],
-        planFile: explicitPlanFile ?? segments.slice(1).join(path.sep),
+        taskName: target.taskName,
+        planFile: explicitPlanFile ?? target.planFile,
     };
 }
+function parseTaskPlanPath(project, planPath) {
+    const relativePlanPath = path.relative(project.tasksDir, planPath);
+    if (relativePlanPath.startsWith("..") || path.isAbsolute(relativePlanPath))
+        return null;
+    const segments = relativePlanPath.split(path.sep).filter(Boolean);
+    const dated = /^\d{4}-\d{2}-\d{2}$/.test(segments[0] ?? "");
+    const taskName = dated ? segments[1] : segments[0];
+    const planFile = (dated ? segments.slice(2) : segments.slice(1)).join(path.sep);
+    return taskName && planFile ? { taskName, planFile } : null;
+}
 function readExplicitAddedTasks(args) {
     return readGroupedValues(args, "--add-task", "--detail", false).map((entry) => ({
         title: entry.value,
@@ -2274,6 +2328,13 @@ function readRepeatedIntegerFlag(args, flag) {
 function failMissingNumericFlag(flag) {
     throw new ClawError("PROJECT_CONFIG_INVALID", `Missing required flag ${flag}.`, { flag });
 }
+function preparePlanEndFinalization(cwd, ownerSessionKey) {
+    const workflowProject = resolveWorkflowProjectContext(cwd, ownerSessionKey);
+    if (workflowProject.scope !== "project")
+        return undefined;
+    const skipGitNexusRefresh = ensureGitNexusReadyForPlanFinalization(cwd);
+    return (taskName) => queueCompletionRefresh({ cwd, taskName, skipGitNexusRefresh });
+}
 function queueCompletionRefresh(input) {
     const project = resolveProjectContext(input.cwd);
     const includeTaskRetention = input.includeTaskRetention ?? true;
@@ -2283,6 +2344,7 @@ function queueCompletionRefresh(input) {
         : {
             enabled: false,
             maxTasksToKeep: project.projectConfig?.maxTasksToKeep ?? DEFAULT_MAX_TASKS_TO_KEEP,
+            archivedTasks: [],
             prunedArchivedTasks: [],
         };
     const startedAt = new Date().toISOString();
@@ -2639,7 +2701,7 @@ function computeCompletionDirtyHash(cwd, taskName, operations) {
     const roots = [
         path.join(project.clawDir, "memory.md"),
         path.join(project.clawDir, "truth"),
-        path.join(project.tasksDir, taskName),
+        findTaskDirectory(project, taskName) ?? path.join(project.tasksDir, taskName),
     ];
     const files = roots.flatMap((root) => listCompletionFingerprintFiles(root)).sort();
     for (const filePath of files) {
@@ -2753,7 +2815,7 @@ function isWindowsAccessViolation(result) {
         && result.status !== null
         && (result.status >>> 0) === 0xc0000005;
 }
-function ensureGitNexusReadyForPlanDone(cwd) {
+function ensureGitNexusReadyForPlanFinalization(cwd) {
     const project = resolveProjectContext(cwd);
     if (project.projectConfig?.gitnexus !== true) {
         return false;