@veewo/claw-core 0.2.3 → 0.2.5

package/dist/src/io.d.ts

@@ -1,5 +1,7 @@
 export declare function readJsonFile<T>(filePath: string): T;
 export declare function writeJsonFile(filePath: string, value: unknown): void;
+export declare function serializeJsonFile(value: unknown): string;
+export declare function writeJsonFileAtomic(filePath: string, value: unknown): void;
 export declare function readTextFile(filePath: string): string;
 export declare function writeTextFile(filePath: string, content: string): void;
 export declare function stripBom(content: string): string;
@@ -8,3 +10,7 @@ export declare function withSerializedAccess<T>(targetPath: string, action: () =
     pollMs?: number;
     timeoutMs?: number;
 }): Promise<T>;
+export declare function withSerializedQueue<T>(queuePath: string, action: () => Promise<T>, options?: {
+    pollMs?: number;
+    timeoutMs?: number;
+}): Promise<T>;

package/dist/src/io.js

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { randomUUID } from "node:crypto";
 import { setTimeout as delay } from "node:timers/promises";
 import { ClawError } from "./errors.js";
 export function readJsonFile(filePath) {
@@ -9,6 +10,30 @@ export function writeJsonFile(filePath, value) {
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
     fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf-8");
 }
+export function serializeJsonFile(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+export function writeJsonFileAtomic(filePath, value) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const temporaryPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.${process.pid}.${randomUUID()}.tmp`);
+    let descriptor;
+    try {
+        descriptor = fs.openSync(temporaryPath, "wx");
+        fs.writeFileSync(descriptor, serializeJsonFile(value), "utf-8");
+        fs.fsyncSync(descriptor);
+        fs.closeSync(descriptor);
+        descriptor = undefined;
+        fs.renameSync(temporaryPath, filePath);
+    }
+    finally {
+        if (descriptor !== undefined) {
+            fs.closeSync(descriptor);
+        }
+        if (fs.existsSync(temporaryPath)) {
+            fs.unlinkSync(temporaryPath);
+        }
+    }
+}
 export function readTextFile(filePath) {
     return stripBom(fs.readFileSync(filePath, "utf-8"));
 }
@@ -67,38 +92,21 @@ async function withFileLockRetry(targetPath, action, options) {
         }
     }
 }
-function readSerializedAccessState(queuePath) {
-    if (!fs.existsSync(queuePath)) {
-        return { nextTicket: 1, serving: 1 };
-    }
-    return JSON.parse(stripBom(fs.readFileSync(queuePath, "utf-8")));
-}
-function writeSerializedAccessState(queuePath, state) {
-    fs.mkdirSync(path.dirname(queuePath), { recursive: true });
-    fs.writeFileSync(queuePath, `${JSON.stringify(state, null, 2)}\n`, "utf-8");
-}
 export async function withSerializedAccess(targetPath, action, options) {
-    const queuePath = `${targetPath}.queue.json`;
+    return withSerializedQueue(`${targetPath}.queue.json`, action, options);
+}
+export async function withSerializedQueue(queuePath, action, options) {
     const pollMs = Math.max(10, options?.pollMs ?? 25);
     const timeoutMs = Math.max(pollMs, options?.timeoutMs ?? 30000);
-    const ticket = await withFileLockRetry(queuePath, () => {
-        const state = readSerializedAccessState(queuePath);
-        const assignedTicket = state.nextTicket;
-        state.nextTicket += 1;
-        writeSerializedAccessState(queuePath, state);
-        return assignedTicket;
-    }, { pollMs, timeoutMs });
+    const token = randomUUID();
     const deadline = Date.now() + timeoutMs;
     while (true) {
-        const state = readSerializedAccessState(queuePath);
-        if (state.serving === ticket) {
+        if (tryAcquireSerializedQueue(queuePath, token)) {
             break;
         }
         if (Date.now() >= deadline) {
-            throw new ClawError("PLAN_WRITE_CONFLICT", `Timed out waiting to serialize access for "${targetPath}".`, {
-                targetPath,
+            throw new ClawError("PLAN_WRITE_CONFLICT", `Timed out waiting to serialize access for queue "${queuePath}".`, {
                 queuePath,
-                ticket,
                 timeoutMs,
             });
         }
@@ -108,17 +116,109 @@ export async function withSerializedAccess(targetPath, action, options) {
         return await action();
     }
     finally {
-        await withFileLockRetry(queuePath, () => {
-            const state = readSerializedAccessState(queuePath);
-            state.serving = Math.max(state.serving, ticket + 1);
-            if (state.serving >= state.nextTicket) {
-                if (fs.existsSync(queuePath)) {
-                    fs.unlinkSync(queuePath);
-                }
-                return;
+        releaseSerializedQueue(queuePath, token);
+    }
+}
+function tryAcquireSerializedQueue(queuePath, token) {
+    fs.mkdirSync(path.dirname(queuePath), { recursive: true });
+    let descriptor;
+    try {
+        descriptor = fs.openSync(queuePath, "wx");
+        const owner = {
+            schemaVersion: 1,
+            token,
+            pid: process.pid,
+            acquiredAt: new Date().toISOString(),
+        };
+        fs.writeFileSync(descriptor, serializeJsonFile(owner), "utf-8");
+        fs.fsyncSync(descriptor);
+        fs.closeSync(descriptor);
+        descriptor = undefined;
+        return true;
+    }
+    catch (error) {
+        if (descriptor !== undefined) {
+            fs.closeSync(descriptor);
+        }
+        const code = error && typeof error === "object" && "code" in error
+            ? String(error.code)
+            : "";
+        if (code !== "EEXIST") {
+            throw error;
+        }
+    }
+    const owner = readSerializedQueueOwner(queuePath);
+    if (!owner) {
+        // Another process may still be flushing the newly-created owner record.
+        // Only treat an unreadable record as abandoned after a short grace period.
+        try {
+            if (Date.now() - fs.statSync(queuePath).mtimeMs < 1000) {
+                return false;
             }
-            writeSerializedAccessState(queuePath, state);
-        }, { pollMs, timeoutMs });
+        }
+        catch {
+            return false;
+        }
+    }
+    else if (isProcessAlive(owner.pid)) {
+        return false;
+    }
+    const stalePath = `${queuePath}.stale.${owner?.token ?? "invalid"}.${randomUUID()}`;
+    try {
+        const current = readSerializedQueueOwner(queuePath);
+        if (owner && current?.token !== owner.token) {
+            return false;
+        }
+        fs.renameSync(queuePath, stalePath);
+        fs.unlinkSync(stalePath);
+    }
+    catch (error) {
+        const code = error && typeof error === "object" && "code" in error
+            ? String(error.code)
+            : "";
+        if (code !== "ENOENT" && code !== "EACCES" && code !== "EPERM") {
+            throw error;
+        }
+    }
+    return false;
+}
+function releaseSerializedQueue(queuePath, token) {
+    try {
+        const owner = readSerializedQueueOwner(queuePath);
+        if (owner?.token === token) {
+            fs.unlinkSync(queuePath);
+        }
+    }
+    catch {
+        // A recovered or externally removed queue is already released.
+    }
+}
+function readSerializedQueueOwner(queuePath) {
+    try {
+        const owner = readJsonFile(queuePath);
+        return owner.schemaVersion === 1
+            && typeof owner.token === "string"
+            && typeof owner.pid === "number"
+            && typeof owner.acquiredAt === "string"
+            ? owner
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        const code = error && typeof error === "object" && "code" in error
+            ? String(error.code)
+            : "";
+        return code === "EPERM";
     }
 }
 //# sourceMappingURL=io.js.map

package/dist/src/io.js.map

@@ -1 +1 @@
-{"version":3,"file":"io.js","sourceRoot":"","sources":["../../src/io.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"io.js","sourceRoot":"","sources":["../../src/io.ts"],"names":[],"mappings":"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"}

package/dist/src/knowledge-assignments.d.ts

@@ -22,6 +22,10 @@ export declare function buildKnowledgeDelegateDispatch(input: {
     finalizeId: string;
     writer?: KnowledgeWriterConfig | null;
 }): KnowledgeDelegateDispatch;
+export declare function buildKnowledgeAtomicDispatch(input: {
+    finalizeId: string;
+    writer?: KnowledgeWriterConfig | null;
+}): KnowledgeDelegateDispatch;
 export declare function buildKnowledgeWriterAssignments(job: Pick<KnowledgeFinalizationJob, "finalizeId" | "planPath" | "reportPath" | "writer">): KnowledgeWriterAssignment[];
 export declare function buildKnowledgeAssignmentTemplate(input: {
     assignments: KnowledgeWriterAssignment[];

package/dist/src/knowledge-assignments.js

@@ -22,6 +22,26 @@ export function buildKnowledgeDelegateDispatch(input) {
         ].join("\n"),
     };
 }
+export function buildKnowledgeAtomicDispatch(input) {
+    return {
+        schemaVersion: 1,
+        policy: "subagent",
+        finalizeId: input.finalizeId,
+        ...(input.writer?.model ? { model: input.writer.model } : {}),
+        ...(input.writer?.reasoningEffort ? { reasoningEffort: input.writer.reasoningEffort } : {}),
+        prompt: [
+            "Execute this already-created claw knowledge-finalization job directly and unattended.",
+            "Use the claw-kit Cindy Ghost tools in the project workspace; do not use the claw CLI for claim or completion.",
+            "Call list_tools for category knowledge, then call_tool knowledge.claim with:",
+            JSON.stringify({ finalizeId: input.finalizeId }),
+            "The claim operation atomically captures the originating Cindy task conclusions into plan.report before it issues the claim token.",
+            "If claimed is false, stop without editing knowledge. If claimed is true, retain claimToken and execute each returned assignment prompt yourself in ascending index order.",
+            "Do not create a claw plan or subplan, invoke another finalizer, or delegate to another agent.",
+            "After a successful claim, call_tool knowledge.done exactly once in a finally-style step with finalizeId, claimToken, status, and result or error.",
+            "Use status succeeded with a concise result only when every assignment succeeds; otherwise use status failed with a concise error.",
+        ].join("\n"),
+    };
+}
 export function buildKnowledgeWriterAssignments(job) {
     const configured = job.writer?.externalSkills?.map((skill) => skill.trim()).filter(Boolean) ?? [];
     if (configured.length === 0) {

package/dist/src/knowledge-assignments.js.map

@@ -1 +1 @@
-{"version":3,"file":"knowledge-assignments.js","sourceRoot":"","sources":["../../src/knowledge-assignments.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAsBzC,MAAM,UAAU,6BAA6B;IAC3C,OAAO,IAAI,CAAC,IAAI,CACd,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAC5C,WAAW,EACX,iBAAiB,EACjB,eAAe,CAChB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,8BAA8B,CAAC,KAI9C;IACC,MAAM,YAAY,GAAG,6BAA6B,EAAE,CAAC;IACrD,MAAM,aAAa,GAAG,uBAAuB,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;IAC7E,OAAO;QACL,aAAa,EAAE,CAAC;QAChB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7D,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,KAAK,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3F,MAAM,EAAE;YACN,uEAAuE;YACvE,gDAAgD,YAAY,cAAc,aAAa,GAAG;YAC1F,wFAAwF;YACxF,oBAAoB,KAAK,CAAC,UAAU,EAAE;YACtC,4GAA4G;SAC7G,CAAC,IAAI,CAAC,IAAI,CAAC;KACb,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,+BAA+B,CAC7C,GAAwF;IAExF,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,EAAE,cAAc,EAAE,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;IAClG,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,CAAC;gBACN,KAAK,EAAE,CAAC;gBACR,IAAI,EAAE,SAAS;gBACf,aAAa,EAAE,CAAC;gBAChB,MAAM,EAAE,2BAA2B,CAAC,GAAG,CAAC;aACzC,CAAC,CAAC;IACL,CAAC;IACD,OAAO,UAAU,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;QACvC,KAAK;QACL,IAAI,EAAE,gBAAgB;QACtB,KAAK;QACL,aAAa,EAAE,CAAC;QAChB,MAAM,EAAE,wBAAwB,CAAC,GAAG,EAAE,KAAK,CAAC;KAC7C,CAAC,CAAC,CAAC;AACN,CAAC;AAED,MAAM,UAAU,gCAAgC,CAAC,KAIhD;IACC,IAAI,KAAK,CAAC,WAAW,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,IAAI,KAAK,SAAS,EAAE,CAAC;QAC/E,OAAO,6BAA6B,CAAC,KAAK,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO;QACL,EAAE,EAAE,yBAAyB,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE;QAC5D,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,KAAK,EAAE,SAAS;QAChB,KAAK,EAAE,8BAA8B;QACrC,MAAM,EAAE,gBAAgB;QACxB,IAAI,EAAE;YACJ,IAAI,EAAE,iEAAiE;SACxE;QACD,YAAY,EAAE;YACZ,OAAO,EAAE,kGAAkG;YAC3G,aAAa,EAAE,EAAE;YACjB,kBAAkB,EAAE;gBAClB,yDAAyD;gBACzD,uDAAuD;gBACvD,2DAA2D;aAC5D;SACF;QACD,KAAK,EAAE,KAAK,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;YAC5C,EAAE,EAAE,UAAU,CAAC,KAAK,GAAG,CAAC;YACxB,KAAK,EAAE,UAAU,CAAC,IAAI,KAAK,SAAS;gBAClC,CAAC,CAAC,uCAAuC;gBACzC,CAAC,CAAC,WAAW,UAAU,CAAC,KAAK,EAAE;YACjC,MAAM,EAAE,UAAU,CAAC,MAAM;YACzB,MAAM,EAAE,SAAS;SAClB,CAAC,CAAC;QACH,UAAU,EAAE,EAAE;QACd,KAAK,EAAE;YACL,8FAA8F;YAC9F,sFAAsF;SACvF;QACD,YAAY,EAAE,EAAE;QAChB,aAAa,EAAE;YACb,OAAO,EAAE,EAAE;SACZ;KACF,CAAC;AACJ,CAAC;AAED,SAAS,6BAA6B,CAAC,KAItC;IACC,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAC5B,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAC5C,WAAW,EACX,kBAAkB,CACnB,CAAC;IACF,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CACvB,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,eAAe,CAAC,EAAE,OAAO,CAAC,CAC3C,CAAC;IAC1B,MAAM,QAAQ,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;IACzC,QAAQ,CAAC,EAAE,GAAG,yBAAyB,KAAK,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC;IACvE,QAAQ,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC;IACjC,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAC;IAC3B,QAAQ,CAAC,KAAK,GAAG,+BAA+B,CAAC;IACjD,QAAQ,CAAC,MAAM,GAAG,gBAAgB,CAAC;IACnC,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACpC,IAAI,SAAS,EAAE,CAAC;QACd,SAAS,CAAC,MAAM,GAAG,GAAG,KAAK,CAAC,WAAW,CAAC,CAAC,CAAE,CAAC,MAAM,OAAO,SAAS,CAAC,MAAM,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC;IAC3F,CAAC;IACD,QAAQ,CAAC,UAAU,GAAG,CAAC,QAAQ,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;QACpE,GAAG,SAAS;QACZ,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,YAAY,EAAE,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;KAC7D,CAAC,CAAC,CAAC;IACJ,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,2BAA2B,CAClC,GAAwF;IAExF,OAAO;QACL,0EAA0E;QAC1E,0GAA0G;QAC1G,mEAAmE,GAAG,CAAC,MAAM,EAAE,mBAAmB,IAAI,CAAC,8HAA8H;QACrO,oBAAoB,CAAC,GAAG,CAAC;KAC1B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,SAAS,wBAAwB,CAC/B,GAA6E,EAC7E,KAAa;IAEb,OAAO;QACL,cAAc,KAAK,gDAAgD;QACnE,4MAA4M;QAC5M,oBAAoB,CAAC,GAAG,CAAC;KAC1B,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,SAAS,oBAAoB,CAC3B,GAA6E;IAE7E,OAAO;QACL,8IAA8I;QAC9I,YAAY;QACZ,KAAK,GAAG,CAAC,QAAQ,EAAE;QACnB,KAAK,GAAG,CAAC,UAAU,EAAE;QACrB,oBAAoB,GAAG,CAAC,UAAU,EAAE;QACpC,wOAAwO;KACzO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}
+{"version":3,"file":"knowledge-assignments.js","sourceRoot":"","sources":["../../src/knowledge-assignments.ts"],"names":[],"mappings":"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"}

package/dist/src/knowledge-sidecar.d.ts

@@ -19,6 +19,8 @@ export type KnowledgeSessionRegistry = {
     sessionId: string;
     activePlanPath?: string;
     activeReportPath?: string;
+    activeWriter?: KnowledgeWriterConfig;
+    activeStartedAt?: string;
     pendingTurnOwner?: KnowledgeReportTarget;
     lastCollectedTurnId?: string;
     updatedAt: string;
@@ -38,6 +40,14 @@ export type KnowledgeFinalizationJob = {
     host?: KnowledgeFinalizationHost | null;
     planPath: string;
     reportPath: string;
+    reportCapture?: {
+        mode: "claim";
+        status: "pending" | "captured";
+        startedAt?: string;
+        capturedAt?: string;
+        transcriptPath?: string;
+        messageCount?: number;
+    };
     status: "queued" | "running" | "succeeded" | "failed";
     attempts: number;
     queuedAt: string;
@@ -98,6 +108,7 @@ export type KnowledgeSidecarResult = {
 };
 export type KnowledgePlanEndResult = KnowledgeSidecarResult & {
     finalizeId?: string;
+    jobPath?: string;
 };
 export type KnowledgeStopResult = KnowledgeSidecarResult & {
     captured?: boolean;
@@ -124,10 +135,13 @@ export declare function deriveKnowledgeFinalizeId(input: {
     planPath: string;
     endedAt: string;
 }): string;
+export declare function resolveKnowledgeWriterForHost(writer: KnowledgeWriterConfig | undefined, host?: string | null): KnowledgeWriterConfig | undefined;
 export declare function tryRegisterKnowledgePlan(input: {
     project: ProjectContext;
     sessionId?: string;
     planPath: string;
+    writer?: KnowledgeWriterConfig;
+    host?: KnowledgeFinalizationHost;
 }): KnowledgeSidecarResult;
 export declare function tryEndKnowledgePlan(input: {
     project: ProjectContext;
@@ -136,6 +150,7 @@ export declare function tryEndKnowledgePlan(input: {
     resumedPlanPath?: string;
     endedAt: string;
     writer?: KnowledgeWriterConfig;
+    host?: KnowledgeFinalizationHost;
 }): KnowledgePlanEndResult;
 /** @deprecated Use tryEndKnowledgePlan for lifecycle-neutral end.* finalization. */
 export declare function tryCompleteKnowledgePlan(input: {
@@ -154,7 +169,9 @@ export declare function tryCaptureKnowledgeStop(input: {
     taskConclusions?: KnowledgeTaskConclusion[];
 }): KnowledgeStopResult;
 export declare function readKnowledgeFinalizationJob(jobPath: string): KnowledgeFinalizationJob;
-export declare function claimKnowledgeFinalizationJob(jobPath: string): KnowledgeFinalizationJob | null;
+export declare function claimKnowledgeFinalizationJob(jobPath: string, options?: {
+    prepare?: (job: KnowledgeFinalizationJob) => Partial<KnowledgeFinalizationJob> | void;
+}): KnowledgeFinalizationJob | null;
 export declare function doneKnowledgeFinalizationJob(input: {
     jobPath: string;
     claimToken: string;
@@ -167,7 +184,14 @@ export declare function doneKnowledgeFinalizationJob(input: {
     job: KnowledgeFinalizationJob;
     alreadyDone: boolean;
 };
-export declare function listRetryableKnowledgeFinalizationJobs(project: ProjectContext): string[];
+export declare function listRetryableKnowledgeFinalizationJobs(project: ProjectContext, options?: {
+    excludeHosts?: KnowledgeFinalizationHost[];
+}): string[];
+export declare function appendKnowledgeTaskConclusions(reportPath: string, sessionId: string, conclusions: KnowledgeTaskConclusion[], capturedAt?: string): {
+    written: number;
+    duplicates: number;
+};
+export declare function listKnowledgeFinalizationJobs(project: ProjectContext): string[];
 /** Remove obsolete legacy runtime records left by releases before task-local jobs. */
 export declare function pruneLegacyKnowledgeRuntime(project: ProjectContext): {
     jobsRemoved: number;

package/dist/src/knowledge-sidecar.js

@@ -57,20 +57,39 @@ export function deriveKnowledgeFinalizeId(input) {
         .update(`${input.sessionId}\n${input.planPath}\n${input.endedAt}`)
         .digest("hex");
 }
+export function resolveKnowledgeWriterForHost(writer, host) {
+    if (host !== "cindy") {
+        return writer;
+    }
+    return {
+        ...(writer ?? {}),
+        executionPolicy: "subagent",
+    };
+}
 export function tryRegisterKnowledgePlan(input) {
     const sessionId = input.sessionId?.trim();
     if (!sessionId) {
         return { ok: true };
     }
     try {
+        const writer = resolveKnowledgeWriterForHost(input.writer, input.host);
         const planPath = toProjectRelativePlanPath(input.project, input.planPath);
         const reportPath = toProjectRelativeReportPath(input.project, deriveKnowledgeReportPath(input.planPath));
-        updateKnowledgeRegistry(input.project, sessionId, (registry) => ({
-            ...registry,
-            activePlanPath: planPath,
-            activeReportPath: reportPath,
-            updatedAt: new Date().toISOString(),
-        }));
+        updateKnowledgeRegistry(input.project, sessionId, (registry) => {
+            const samePlan = registry.activePlanPath === planPath;
+            const continuingSubagentCapture = writer?.executionPolicy === "subagent"
+                && registry.activeWriter?.executionPolicy === "subagent";
+            return {
+                ...registry,
+                activePlanPath: planPath,
+                activeReportPath: reportPath,
+                ...(writer ? { activeWriter: writer } : {}),
+                activeStartedAt: (samePlan || continuingSubagentCapture) && registry.activeStartedAt
+                    ? registry.activeStartedAt
+                    : new Date().toISOString(),
+                updatedAt: new Date().toISOString(),
+            };
+        });
         return { ok: true };
     }
     catch (error) {
@@ -83,6 +102,7 @@ export function tryEndKnowledgePlan(input) {
         return { ok: true };
     }
     try {
+        const writer = resolveKnowledgeWriterForHost(input.writer, input.host);
         const endedPlanPath = toProjectRelativePlanPath(input.project, input.endedPlanPath);
         const reportPath = toProjectRelativeReportPath(input.project, deriveKnowledgeReportPath(input.endedPlanPath));
         const resumedPlanPath = input.resumedPlanPath
@@ -96,21 +116,69 @@ export function tryEndKnowledgePlan(input) {
             planPath: endedPlanPath,
             endedAt: input.endedAt,
         });
-        updateKnowledgeRegistry(input.project, sessionId, (registry) => ({
-            ...registry,
-            ...(resumedPlanPath
-                ? { activePlanPath: resumedPlanPath, activeReportPath: resumedReportPath }
-                : { activePlanPath: undefined, activeReportPath: undefined }),
-            pendingTurnOwner: {
-                planPath: endedPlanPath,
-                reportPath,
-                finalizeId,
-                ...(input.writer ? { writer: input.writer } : {}),
-                endedAt: input.endedAt,
-            },
-            updatedAt: new Date().toISOString(),
-        }));
-        return { ok: true, finalizeId };
+        let jobPath;
+        updateKnowledgeRegistry(input.project, sessionId, (registry) => {
+            const common = {
+                ...registry,
+                ...(resumedPlanPath
+                    ? {
+                        activePlanPath: resumedPlanPath,
+                        activeReportPath: resumedReportPath,
+                        activeWriter: writer,
+                        activeStartedAt: registry.activeStartedAt,
+                    }
+                    : { activePlanPath: undefined, activeReportPath: undefined, activeWriter: undefined, activeStartedAt: undefined }),
+                updatedAt: new Date().toISOString(),
+            };
+            if (writer?.executionPolicy !== "subagent") {
+                return {
+                    ...common,
+                    pendingTurnOwner: {
+                        planPath: endedPlanPath,
+                        reportPath,
+                        finalizeId,
+                        ...(writer ? { writer } : {}),
+                        endedAt: input.endedAt,
+                    },
+                };
+            }
+            const subagentCommon = {
+                ...common,
+                pendingTurnOwner: undefined,
+            };
+            if (resumedPlanPath) {
+                return subagentCommon;
+            }
+            const absolutePlanPath = resolveProjectRelativePlanPath(input.project, endedPlanPath);
+            const absoluteReportPath = resolveProjectRelativeReportPath(input.project, reportPath);
+            jobPath = knowledgeFinalizationJobPathForPlan(input.project, absolutePlanPath, finalizeId);
+            if (!fs.existsSync(jobPath)) {
+                writeJsonFile(jobPath, {
+                    schemaVersion: 1,
+                    finalizeId,
+                    sessionId,
+                    projectRoot: input.project.projectRoot,
+                    taskName: taskNameFromPlanPath(endedPlanPath),
+                    writer,
+                    host: input.host ?? null,
+                    planPath: absolutePlanPath,
+                    reportPath: absoluteReportPath,
+                    reportCapture: {
+                        mode: "claim",
+                        status: "pending",
+                        ...(registry.activeStartedAt ? { startedAt: registry.activeStartedAt } : {}),
+                    },
+                    status: "queued",
+                    attempts: 0,
+                    queuedAt: new Date().toISOString(),
+                });
+            }
+            return subagentCommon;
+        });
+        if (writer?.executionPolicy === "subagent" && resumedPlanPath) {
+            return { ok: true };
+        }
+        return { ok: true, finalizeId, ...(jobPath ? { jobPath } : {}) };
     }
     catch (error) {
         return { ok: false, error: errorMessage(error) };
@@ -141,26 +209,18 @@ export function tryCaptureKnowledgeStop(input) {
         return withFileLock(registryPath, () => {
             const registry = readKnowledgeRegistry(registryPath, sessionId);
             const target = registry.pendingTurnOwner ?? (registry.activePlanPath && registry.activeReportPath
-                ? { planPath: registry.activePlanPath, reportPath: registry.activeReportPath }
+                ? { planPath: registry.activePlanPath, reportPath: registry.activeReportPath, writer: registry.activeWriter }
                 : undefined);
             if (!target) {
                 return { ok: true, captured: false };
             }
+            if (target.writer?.executionPolicy === "subagent"
+                || (!target.writer && input.project.projectConfig?.knowledgeWriter?.executionPolicy === "subagent")) {
+                return { ok: true, captured: false };
+            }
             const reportPath = resolveProjectRelativeReportPath(input.project, target.reportPath);
             const capturedAt = new Date().toISOString();
-            for (const conclusion of input.taskConclusions ?? []) {
-                if (conclusion.turnId !== turnId) {
-                    continue;
-                }
-                appendKnowledgeReportEntry(reportPath, {
-                    schemaVersion: 1,
-                    entryType: "task_conclusion",
-                    sessionId,
-                    turnId: conclusion.turnId,
-                    capturedAt,
-                    message: conclusion.message,
-                });
-            }
+            appendKnowledgeTaskConclusions(reportPath, sessionId, (input.taskConclusions ?? []).filter((conclusion) => conclusion.turnId === turnId), capturedAt);
             const duplicate = appendKnowledgeReportEntry(reportPath, {
                 schemaVersion: 1,
                 sessionId,
@@ -238,15 +298,17 @@ export function tryCaptureKnowledgeStop(input) {
 export function readKnowledgeFinalizationJob(jobPath) {
     return readJsonFile(jobPath);
 }
-export function claimKnowledgeFinalizationJob(jobPath) {
+export function claimKnowledgeFinalizationJob(jobPath, options) {
     return withFileLock(jobPath, () => {
         const current = readJsonFile(jobPath);
         if (current.status === "succeeded" || current.status === "running" || current.attempts >= 3) {
             return null;
         }
         const now = new Date().toISOString();
+        const prepared = options?.prepare?.(structuredClone(current));
         const running = {
             ...current,
+            ...(prepared ?? {}),
             status: "running",
             attempts: current.attempts + 1,
             startedAt: now,
@@ -292,24 +354,49 @@ export function doneKnowledgeFinalizationJob(input) {
         return { job: terminal, alreadyDone: false };
     });
 }
-export function listRetryableKnowledgeFinalizationJobs(project) {
-    const taskJobs = listTaskDirectories(project)
-        .flatMap((task) => listKnowledgeJobs(path.join(task.taskDir, ".runtime", "knowledge-finalization")));
-    const archivedTaskJobs = listTaskDirectories({ tasksDir: path.join(project.clawDir, "archive", "tasks") })
-        .flatMap((task) => listKnowledgeJobs(path.join(task.taskDir, ".runtime", "knowledge-finalization")));
-    // Read legacy central jobs so an upgrade does not strand retryable work. New jobs are never written there.
-    const legacyJobs = listKnowledgeJobs(path.join(project.clawDir, "runtime", "knowledge-finalization", "jobs"));
-    return [...taskJobs, ...archivedTaskJobs, ...legacyJobs]
+export function listRetryableKnowledgeFinalizationJobs(project, options = {}) {
+    const excludedHosts = new Set(options.excludeHosts ?? []);
+    return listKnowledgeFinalizationJobs(project)
         .filter((jobPath) => {
         try {
             const job = readKnowledgeFinalizationJob(jobPath);
-            return (job.status === "queued" || job.status === "failed") && job.attempts < 3;
+            return (job.status === "queued" || job.status === "failed")
+                && job.attempts < 3
+                && !excludedHosts.has(job.host);
         }
         catch {
             return false;
         }
     });
 }
+export function appendKnowledgeTaskConclusions(reportPath, sessionId, conclusions, capturedAt = new Date().toISOString()) {
+    let written = 0;
+    let duplicates = 0;
+    for (const conclusion of conclusions) {
+        const entry = {
+            schemaVersion: 1,
+            entryType: "task_conclusion",
+            sessionId,
+            turnId: conclusion.turnId,
+            capturedAt,
+            message: conclusion.message,
+        };
+        if (appendKnowledgeReportEntry(reportPath, entry))
+            duplicates += 1;
+        else
+            written += 1;
+    }
+    return { written, duplicates };
+}
+export function listKnowledgeFinalizationJobs(project) {
+    const taskJobs = listTaskDirectories(project)
+        .flatMap((task) => listKnowledgeJobs(path.join(task.taskDir, ".runtime", "knowledge-finalization")));
+    const archivedTaskJobs = listTaskDirectories({ tasksDir: path.join(project.clawDir, "archive", "tasks") })
+        .flatMap((task) => listKnowledgeJobs(path.join(task.taskDir, ".runtime", "knowledge-finalization")));
+    // Read legacy central jobs so an upgrade does not strand retryable work. New jobs are never written there.
+    const legacyJobs = listKnowledgeJobs(path.join(project.clawDir, "runtime", "knowledge-finalization", "jobs"));
+    return [...taskJobs, ...archivedTaskJobs, ...legacyJobs];
+}
 /** Remove obsolete legacy runtime records left by releases before task-local jobs. */
 export function pruneLegacyKnowledgeRuntime(project) {
     const legacyJobsDir = path.join(project.clawDir, "runtime", "knowledge-finalization", "jobs");