gsd-pi 2.44.0 → 2.45.0-dev.1afbdaa

package/dist/resources/extensions/gsd/tools/plan-task.js

@@ -2,6 +2,9 @@ import { clearParseCache } from "../files.js";
 import { transaction, getSlice, getTask, insertTask, upsertTaskPlanning } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { renderTaskPlanFromDb } from "../markdown-renderer.js";
+import { renderAllProjections } from "../workflow-projections.js";
+import { writeManifest } from "../workflow-manifest.js";
+import { appendEvent } from "../workflow-events.js";
 function isNonEmptyString(value) {
     return typeof value === "string" && value.trim().length > 0;
 }
@@ -51,9 +54,16 @@ export async function handlePlanTask(rawParams, basePath) {
     if (!parentSlice) {
         return { error: `missing parent slice: ${params.milestoneId}/${params.sliceId}` };
     }
+    if (parentSlice.status === "complete" || parentSlice.status === "done") {
+        return { error: `cannot plan task in a closed slice: ${params.sliceId} (status: ${parentSlice.status})` };
+    }
+    const existingTask = getTask(params.milestoneId, params.sliceId, params.taskId);
+    if (existingTask && (existingTask.status === "complete" || existingTask.status === "done")) {
+        return { error: `cannot re-plan task ${params.taskId}: it is already complete — use gsd_task_reopen first` };
+    }
     try {
         transaction(() => {
-            if (!getTask(params.milestoneId, params.sliceId, params.taskId)) {
+            if (!existingTask) {
                 insertTask({
                     id: params.taskId,
                     sliceId: params.sliceId,
@@ -71,6 +81,7 @@ export async function handlePlanTask(rawParams, basePath) {
                 inputs: params.inputs,
                 expectedOutput: params.expectedOutput,
                 observabilityImpact: params.observabilityImpact ?? "",
+                fullPlanMd: params.fullPlanMd,
             });
         });
     }
@@ -81,6 +92,22 @@ export async function handlePlanTask(rawParams, basePath) {
         const renderResult = await renderTaskPlanFromDb(basePath, params.milestoneId, params.sliceId, params.taskId);
         invalidateStateCache();
         clearParseCache();
+        // ── Post-mutation hook: projections, manifest, event log ─────────────
+        try {
+            await renderAllProjections(basePath, params.milestoneId);
+            writeManifest(basePath);
+            appendEvent(basePath, {
+                cmd: "plan-task",
+                params: { milestoneId: params.milestoneId, sliceId: params.sliceId, taskId: params.taskId },
+                ts: new Date().toISOString(),
+                actor: "agent",
+                actor_name: params.actorName,
+                trigger_reason: params.triggerReason,
+            });
+        }
+        catch (hookErr) {
+            process.stderr.write(`gsd: plan-task post-mutation hook warning: ${hookErr.message}\n`);
+        }
         return {
             milestoneId: params.milestoneId,
             sliceId: params.sliceId,

package/dist/resources/extensions/gsd/tools/reassess-roadmap.js

@@ -1,7 +1,10 @@
 import { clearParseCache } from "../files.js";
-import { transaction, getMilestone, getMilestoneSlices, insertSlice, updateSliceFields, insertAssessment, deleteSlice, } from "../gsd-db.js";
+import { transaction, getMilestone, getMilestoneSlices, getSlice, insertSlice, updateSliceFields, insertAssessment, deleteSlice, } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { renderRoadmapFromDb, renderAssessmentFromDb } from "../markdown-renderer.js";
+import { renderAllProjections } from "../workflow-projections.js";
+import { writeManifest } from "../workflow-manifest.js";
+import { appendEvent } from "../workflow-events.js";
 import { join } from "node:path";
 function isNonEmptyString(value) {
     return typeof value === "string" && value.trim().length > 0;
@@ -58,11 +61,22 @@ export async function handleReassessRoadmap(rawParams, basePath) {
     catch (err) {
         return { error: `validation failed: ${err.message}` };
     }
-    // ── Verify milestone exists ───────────────────────────────────────
+    // ── Verify milestone exists and is active ────────────────────────
     const milestone = getMilestone(params.milestoneId);
     if (!milestone) {
         return { error: `milestone not found: ${params.milestoneId}` };
     }
+    if (milestone.status === "complete" || milestone.status === "done") {
+        return { error: `cannot reassess a closed milestone: ${params.milestoneId} (status: ${milestone.status})` };
+    }
+    // ── Verify completedSliceId is actually complete ──────────────────
+    const completedSlice = getSlice(params.milestoneId, params.completedSliceId);
+    if (!completedSlice) {
+        return { error: `completedSliceId not found: ${params.milestoneId}/${params.completedSliceId}` };
+    }
+    if (completedSlice.status !== "complete" && completedSlice.status !== "done") {
+        return { error: `completedSliceId ${params.completedSliceId} is not complete (status: ${completedSlice.status}) — reassess can only be called after a slice finishes` };
+    }
     // ── Structural enforcement ────────────────────────────────────────
     const existingSlices = getMilestoneSlices(params.milestoneId);
     const completedSliceIds = new Set();
@@ -139,6 +153,22 @@ export async function handleReassessRoadmap(rawParams, basePath) {
         // ── Invalidate caches ─────────────────────────────────────────
         invalidateStateCache();
         clearParseCache();
+        // ── Post-mutation hook: projections, manifest, event log ─────
+        try {
+            await renderAllProjections(basePath, params.milestoneId);
+            writeManifest(basePath);
+            appendEvent(basePath, {
+                cmd: "reassess-roadmap",
+                params: { milestoneId: params.milestoneId, completedSliceId: params.completedSliceId },
+                ts: new Date().toISOString(),
+                actor: "agent",
+                actor_name: params.actorName,
+                trigger_reason: params.triggerReason,
+            });
+        }
+        catch (hookErr) {
+            process.stderr.write(`gsd: reassess-roadmap post-mutation hook warning: ${hookErr.message}\n`);
+        }
         return {
             milestoneId: params.milestoneId,
             completedSliceId: params.completedSliceId,

package/dist/resources/extensions/gsd/tools/reopen-slice.js

@@ -0,0 +1,86 @@
+/**
+ * reopen-slice handler — the core operation behind gsd_slice_reopen.
+ *
+ * Resets a completed slice back to "in_progress" and resets ALL of its
+ * tasks back to "pending". This is intentional — if you're reopening a
+ * slice, you're re-doing the work. Partial resets create ambiguous state.
+ *
+ * The parent milestone must still be open (not complete).
+ */
+// GSD — reopen-slice tool handler
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+import { getMilestone, getSlice, getSliceTasks, updateSliceStatus, updateTaskStatus, transaction, } from "../gsd-db.js";
+import { invalidateStateCache } from "../state.js";
+import { renderAllProjections } from "../workflow-projections.js";
+import { writeManifest } from "../workflow-manifest.js";
+import { appendEvent } from "../workflow-events.js";
+export async function handleReopenSlice(params, basePath) {
+    // ── Validate required fields ────────────────────────────────────────────
+    if (!params.sliceId || typeof params.sliceId !== "string" || params.sliceId.trim() === "") {
+        return { error: "sliceId is required and must be a non-empty string" };
+    }
+    if (!params.milestoneId || typeof params.milestoneId !== "string" || params.milestoneId.trim() === "") {
+        return { error: "milestoneId is required and must be a non-empty string" };
+    }
+    // ── Guards + DB writes inside a single transaction (prevents TOCTOU) ───
+    let guardError = null;
+    let tasksResetCount = 0;
+    transaction(() => {
+        const milestone = getMilestone(params.milestoneId);
+        if (!milestone) {
+            guardError = `milestone not found: ${params.milestoneId}`;
+            return;
+        }
+        if (milestone.status === "complete" || milestone.status === "done") {
+            guardError = `cannot reopen slice inside a closed milestone: ${params.milestoneId} (status: ${milestone.status})`;
+            return;
+        }
+        const slice = getSlice(params.milestoneId, params.sliceId);
+        if (!slice) {
+            guardError = `slice not found: ${params.milestoneId}/${params.sliceId}`;
+            return;
+        }
+        if (slice.status !== "complete" && slice.status !== "done") {
+            guardError = `slice ${params.sliceId} is not complete (status: ${slice.status}) — nothing to reopen`;
+            return;
+        }
+        // Fetch tasks inside txn so the list is consistent with the slice status check
+        const tasks = getSliceTasks(params.milestoneId, params.sliceId);
+        tasksResetCount = tasks.length;
+        updateSliceStatus(params.milestoneId, params.sliceId, "in_progress");
+        for (const task of tasks) {
+            updateTaskStatus(params.milestoneId, params.sliceId, task.id, "pending");
+        }
+    });
+    if (guardError) {
+        return { error: guardError };
+    }
+    // ── Invalidate caches ────────────────────────────────────────────────────
+    invalidateStateCache();
+    // ── Post-mutation hook ───────────────────────────────────────────────────
+    try {
+        await renderAllProjections(basePath, params.milestoneId);
+        writeManifest(basePath);
+        appendEvent(basePath, {
+            cmd: "reopen-slice",
+            params: {
+                milestoneId: params.milestoneId,
+                sliceId: params.sliceId,
+                reason: params.reason ?? null,
+                tasksReset: tasksResetCount,
+            },
+            ts: new Date().toISOString(),
+            actor: "agent",
+            actor_name: params.actorName,
+            trigger_reason: params.triggerReason,
+        });
+    }
+    catch (hookErr) {
+        process.stderr.write(`gsd: reopen-slice post-mutation hook warning: ${hookErr.message}\n`);
+    }
+    return {
+        milestoneId: params.milestoneId,
+        sliceId: params.sliceId,
+        tasksReset: tasksResetCount,
+    };
+}

package/dist/resources/extensions/gsd/tools/reopen-task.js

@@ -0,0 +1,90 @@
+/**
+ * reopen-task handler — the core operation behind gsd_task_reopen.
+ *
+ * Resets a completed task back to "pending" so it can be re-done
+ * without manual SQL surgery. The parent slice and milestone must
+ * still be open (not complete) — you cannot reopen tasks inside a
+ * closed slice.
+ */
+// GSD — reopen-task tool handler
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+import { getMilestone, getSlice, getTask, updateTaskStatus, transaction, } from "../gsd-db.js";
+import { invalidateStateCache } from "../state.js";
+import { renderAllProjections } from "../workflow-projections.js";
+import { writeManifest } from "../workflow-manifest.js";
+import { appendEvent } from "../workflow-events.js";
+export async function handleReopenTask(params, basePath) {
+    // ── Validate required fields ────────────────────────────────────────────
+    if (!params.taskId || typeof params.taskId !== "string" || params.taskId.trim() === "") {
+        return { error: "taskId is required and must be a non-empty string" };
+    }
+    if (!params.sliceId || typeof params.sliceId !== "string" || params.sliceId.trim() === "") {
+        return { error: "sliceId is required and must be a non-empty string" };
+    }
+    if (!params.milestoneId || typeof params.milestoneId !== "string" || params.milestoneId.trim() === "") {
+        return { error: "milestoneId is required and must be a non-empty string" };
+    }
+    // ── Guards + DB write inside a single transaction (prevents TOCTOU) ────
+    let guardError = null;
+    transaction(() => {
+        const milestone = getMilestone(params.milestoneId);
+        if (!milestone) {
+            guardError = `milestone not found: ${params.milestoneId}`;
+            return;
+        }
+        if (milestone.status === "complete" || milestone.status === "done") {
+            guardError = `cannot reopen task in a closed milestone: ${params.milestoneId} (status: ${milestone.status})`;
+            return;
+        }
+        const slice = getSlice(params.milestoneId, params.sliceId);
+        if (!slice) {
+            guardError = `slice not found: ${params.milestoneId}/${params.sliceId}`;
+            return;
+        }
+        if (slice.status === "complete" || slice.status === "done") {
+            guardError = `cannot reopen task inside a closed slice: ${params.sliceId} (status: ${slice.status}) — use gsd_slice_reopen first`;
+            return;
+        }
+        const task = getTask(params.milestoneId, params.sliceId, params.taskId);
+        if (!task) {
+            guardError = `task not found: ${params.milestoneId}/${params.sliceId}/${params.taskId}`;
+            return;
+        }
+        if (task.status !== "complete" && task.status !== "done") {
+            guardError = `task ${params.taskId} is not complete (status: ${task.status}) — nothing to reopen`;
+            return;
+        }
+        updateTaskStatus(params.milestoneId, params.sliceId, params.taskId, "pending");
+    });
+    if (guardError) {
+        return { error: guardError };
+    }
+    // ── Invalidate caches ────────────────────────────────────────────────────
+    invalidateStateCache();
+    // ── Post-mutation hook ───────────────────────────────────────────────────
+    try {
+        await renderAllProjections(basePath, params.milestoneId);
+        writeManifest(basePath);
+        appendEvent(basePath, {
+            cmd: "reopen-task",
+            params: {
+                milestoneId: params.milestoneId,
+                sliceId: params.sliceId,
+                taskId: params.taskId,
+                reason: params.reason ?? null,
+            },
+            ts: new Date().toISOString(),
+            actor: "agent",
+            actor_name: params.actorName,
+            trigger_reason: params.triggerReason,
+        });
+    }
+    catch (hookErr) {
+        process.stderr.write(`gsd: reopen-task post-mutation hook warning: ${hookErr.message}\n`);
+    }
+    return {
+        milestoneId: params.milestoneId,
+        sliceId: params.sliceId,
+        taskId: params.taskId,
+    };
+}

package/dist/resources/extensions/gsd/tools/replan-slice.js

@@ -1,7 +1,10 @@
 import { clearParseCache } from "../files.js";
-import { transaction, getSlice, getSliceTasks, insertTask, upsertTaskPlanning, insertReplanHistory, deleteTask, } from "../gsd-db.js";
+import { transaction, getSlice, getSliceTasks, getTask, insertTask, upsertTaskPlanning, insertReplanHistory, deleteTask, } from "../gsd-db.js";
 import { invalidateStateCache } from "../state.js";
 import { renderPlanFromDb, renderReplanFromDb } from "../markdown-renderer.js";
+import { renderAllProjections } from "../workflow-projections.js";
+import { writeManifest } from "../workflow-manifest.js";
+import { appendEvent } from "../workflow-events.js";
 function isNonEmptyString(value) {
     return typeof value === "string" && value.trim().length > 0;
 }
@@ -43,11 +46,22 @@ export async function handleReplanSlice(rawParams, basePath) {
     catch (err) {
         return { error: `validation failed: ${err.message}` };
     }
-    // ── Verify parent slice exists ────────────────────────────────────
+    // ── Verify parent slice exists and is not closed ─────────────────
     const parentSlice = getSlice(params.milestoneId, params.sliceId);
     if (!parentSlice) {
         return { error: `missing parent slice: ${params.milestoneId}/${params.sliceId}` };
     }
+    if (parentSlice.status === "complete" || parentSlice.status === "done") {
+        return { error: `cannot replan a closed slice: ${params.sliceId} (status: ${parentSlice.status})` };
+    }
+    // ── Verify blocker task exists and is complete ────────────────────
+    const blockerTask = getTask(params.milestoneId, params.sliceId, params.blockerTaskId);
+    if (!blockerTask) {
+        return { error: `blockerTaskId not found: ${params.milestoneId}/${params.sliceId}/${params.blockerTaskId}` };
+    }
+    if (blockerTask.status !== "complete" && blockerTask.status !== "done") {
+        return { error: `blockerTaskId ${params.blockerTaskId} is not complete (status: ${blockerTask.status}) — the blocker task must be finished before a replan is triggered` };
+    }
     // ── Structural enforcement ────────────────────────────────────────
     const existingTasks = getSliceTasks(params.milestoneId, params.sliceId);
     const completedTaskIds = new Set();
@@ -91,6 +105,7 @@ export async function handleReplanSlice(rawParams, basePath) {
                         verify: updatedTask.verify || "",
                         inputs: updatedTask.inputs || [],
                         expectedOutput: updatedTask.expectedOutput || [],
+                        fullPlanMd: updatedTask.fullPlanMd,
                     });
                 }
                 else {
@@ -110,6 +125,7 @@ export async function handleReplanSlice(rawParams, basePath) {
                         verify: updatedTask.verify || "",
                         inputs: updatedTask.inputs || [],
                         expectedOutput: updatedTask.expectedOutput || [],
+                        fullPlanMd: updatedTask.fullPlanMd,
                     });
                 }
             }
@@ -133,6 +149,22 @@ export async function handleReplanSlice(rawParams, basePath) {
         // ── Invalidate caches ─────────────────────────────────────────
         invalidateStateCache();
         clearParseCache();
+        // ── Post-mutation hook: projections, manifest, event log ─────
+        try {
+            await renderAllProjections(basePath, params.milestoneId);
+            writeManifest(basePath);
+            appendEvent(basePath, {
+                cmd: "replan-slice",
+                params: { milestoneId: params.milestoneId, sliceId: params.sliceId, blockerTaskId: params.blockerTaskId },
+                ts: new Date().toISOString(),
+                actor: "agent",
+                actor_name: params.actorName,
+                trigger_reason: params.triggerReason,
+            });
+        }
+        catch (hookErr) {
+            process.stderr.write(`gsd: replan-slice post-mutation hook warning: ${hookErr.message}\n`);
+        }
         return {
             milestoneId: params.milestoneId,
             sliceId: params.sliceId,

package/dist/resources/extensions/gsd/tools/validate-milestone.js

@@ -0,0 +1,88 @@
+/**
+ * validate-milestone handler — the core operation behind gsd_validate_milestone.
+ *
+ * Persists milestone validation results to the assessments table,
+ * renders VALIDATION.md to disk, and invalidates caches.
+ */
+import { join } from "node:path";
+import { transaction, _getAdapter, } from "../gsd-db.js";
+import { resolveMilestonePath, clearPathCache } from "../paths.js";
+import { saveFile, clearParseCache } from "../files.js";
+import { invalidateStateCache } from "../state.js";
+function renderValidationMarkdown(params) {
+    let md = `---
+verdict: ${params.verdict}
+remediation_round: ${params.remediationRound}
+---
+
+# Milestone Validation: ${params.milestoneId}
+
+## Success Criteria Checklist
+${params.successCriteriaChecklist}
+
+## Slice Delivery Audit
+${params.sliceDeliveryAudit}
+
+## Cross-Slice Integration
+${params.crossSliceIntegration}
+
+## Requirement Coverage
+${params.requirementCoverage}
+
+## Verdict Rationale
+${params.verdictRationale}
+`;
+    if (params.verdict === "needs-remediation" && params.remediationPlan) {
+        md += `\n## Remediation Plan\n${params.remediationPlan}\n`;
+    }
+    return md;
+}
+export async function handleValidateMilestone(params, basePath) {
+    if (!params.milestoneId || typeof params.milestoneId !== "string" || params.milestoneId.trim() === "") {
+        return { error: "milestoneId is required and must be a non-empty string" };
+    }
+    const validVerdicts = ["pass", "needs-attention", "needs-remediation"];
+    if (!validVerdicts.includes(params.verdict)) {
+        return { error: `verdict must be one of: ${validVerdicts.join(", ")}` };
+    }
+    // ── Filesystem render ──────────────────────────────────────────────────
+    const validationMd = renderValidationMarkdown(params);
+    let validationPath;
+    const milestoneDir = resolveMilestonePath(basePath, params.milestoneId);
+    if (milestoneDir) {
+        validationPath = join(milestoneDir, `${params.milestoneId}-VALIDATION.md`);
+    }
+    else {
+        const gsdDir = join(basePath, ".gsd");
+        const manualDir = join(gsdDir, "milestones", params.milestoneId);
+        validationPath = join(manualDir, `${params.milestoneId}-VALIDATION.md`);
+    }
+    try {
+        await saveFile(validationPath, validationMd);
+    }
+    catch (renderErr) {
+        process.stderr.write(`gsd-db: validate_milestone — disk render failed: ${renderErr.message}\n`);
+        return { error: `disk render failed: ${renderErr.message}` };
+    }
+    // ── DB write — store in assessments table ──────────────────────────────
+    const validatedAt = new Date().toISOString();
+    transaction(() => {
+        const adapter = _getAdapter();
+        adapter.prepare(`INSERT OR REPLACE INTO assessments (path, milestone_id, slice_id, task_id, status, scope, full_content, created_at)
+       VALUES (:path, :mid, NULL, NULL, :verdict, 'milestone-validation', :content, :created_at)`).run({
+            ":path": validationPath,
+            ":mid": params.milestoneId,
+            ":verdict": params.verdict,
+            ":content": validationMd,
+            ":created_at": validatedAt,
+        });
+    });
+    invalidateStateCache();
+    clearPathCache();
+    clearParseCache();
+    return {
+        milestoneId: params.milestoneId,
+        verdict: params.verdict,
+        validationPath,
+    };
+}

package/dist/resources/extensions/gsd/unit-ownership.js

@@ -0,0 +1,85 @@
+// GSD Extension — Unit Ownership
+// Opt-in per-unit ownership claims for multi-agent safety.
+//
+// An agent can claim a unit (task, slice) before working on it.
+// complete-task and complete-slice enforce ownership when claims exist.
+// If no claim file is present, ownership is not enforced (backward compatible).
+//
+// Claim file location: .gsd/unit-claims.json
+// Unit key format:
+//   task:  "<milestoneId>/<sliceId>/<taskId>"
+//   slice: "<milestoneId>/<sliceId>"
+//
+// Copyright (c) 2026 Jeremy McSpadden <jeremy@fluxlabs.net>
+import { existsSync, readFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteSync } from "./atomic-write.js";
+// ─── Key Builders ────────────────────────────────────────────────────────
+export function taskUnitKey(milestoneId, sliceId, taskId) {
+    return `${milestoneId}/${sliceId}/${taskId}`;
+}
+export function sliceUnitKey(milestoneId, sliceId) {
+    return `${milestoneId}/${sliceId}`;
+}
+// ─── File Path ───────────────────────────────────────────────────────────
+function claimsPath(basePath) {
+    return join(basePath, ".gsd", "unit-claims.json");
+}
+// ─── Read Claims ─────────────────────────────────────────────────────────
+function readClaims(basePath) {
+    const path = claimsPath(basePath);
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+}
+// ─── Public API ──────────────────────────────────────────────────────────
+/**
+ * Claim a unit for an agent.
+ * Overwrites any existing claim for this unit (last writer wins).
+ */
+export function claimUnit(basePath, unitKey, agentName) {
+    const claims = readClaims(basePath) ?? {};
+    claims[unitKey] = { agent: agentName, claimed_at: new Date().toISOString() };
+    const dir = join(basePath, ".gsd");
+    mkdirSync(dir, { recursive: true });
+    atomicWriteSync(claimsPath(basePath), JSON.stringify(claims, null, 2) + "\n");
+}
+/**
+ * Release a unit claim (remove it from the claims map).
+ */
+export function releaseUnit(basePath, unitKey) {
+    const claims = readClaims(basePath);
+    if (!claims || !(unitKey in claims))
+        return;
+    delete claims[unitKey];
+    atomicWriteSync(claimsPath(basePath), JSON.stringify(claims, null, 2) + "\n");
+}
+/**
+ * Get the current owner of a unit, or null if unclaimed / no claims file.
+ */
+export function getOwner(basePath, unitKey) {
+    const claims = readClaims(basePath);
+    if (!claims)
+        return null;
+    return claims[unitKey]?.agent ?? null;
+}
+/**
+ * Check if an actor is authorized to operate on a unit.
+ * Returns null if ownership passes (or is unclaimed / no file).
+ * Returns an error string if a different agent owns the unit.
+ */
+export function checkOwnership(basePath, unitKey, actorName) {
+    if (!actorName)
+        return null; // no actor identity provided — opt-in, so allow
+    const owner = getOwner(basePath, unitKey);
+    if (owner === null)
+        return null; // unit unclaimed or no claims file
+    if (owner === actorName)
+        return null; // actor is the owner
+    return `Unit ${unitKey} is owned by ${owner}, not ${actorName}`;
+}

package/dist/resources/extensions/gsd/workflow-events.js

@@ -0,0 +1,102 @@
+import { createHash, randomUUID } from "node:crypto";
+import { appendFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { atomicWriteSync } from "./atomic-write.js";
+// ─── Session ID ───────────────────────────────────────────────────────────
+/**
+ * Engine-generated session ID — stable for the lifetime of this process.
+ * Agents can reference this to correlate all events from one run.
+ */
+const ENGINE_SESSION_ID = randomUUID();
+export function getSessionId() {
+    return ENGINE_SESSION_ID;
+}
+// ─── appendEvent ─────────────────────────────────────────────────────────
+/**
+ * Append one event to .gsd/event-log.jsonl.
+ * Computes a content hash from cmd+params (deterministic, independent of ts/actor/session).
+ * Creates .gsd directory if needed.
+ */
+export function appendEvent(basePath, event) {
+    const hash = createHash("sha256")
+        .update(JSON.stringify({ cmd: event.cmd, params: event.params, ts: event.ts }))
+        .digest("hex")
+        .slice(0, 16);
+    const fullEvent = {
+        ...event,
+        hash,
+        session_id: ENGINE_SESSION_ID,
+    };
+    const dir = join(basePath, ".gsd");
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(join(dir, "event-log.jsonl"), JSON.stringify(fullEvent) + "\n", "utf-8");
+}
+// ─── readEvents ──────────────────────────────────────────────────────────
+/**
+ * Read all events from a JSONL file.
+ * Returns empty array if file doesn't exist.
+ * Corrupted lines are skipped with stderr warning.
+ */
+export function readEvents(logPath) {
+    if (!existsSync(logPath)) {
+        return [];
+    }
+    const content = readFileSync(logPath, "utf-8");
+    const lines = content.split("\n").filter((l) => l.length > 0);
+    const events = [];
+    for (const line of lines) {
+        try {
+            events.push(JSON.parse(line));
+        }
+        catch {
+            process.stderr.write(`workflow-events: skipping corrupted event line: ${line.slice(0, 80)}\n`);
+        }
+    }
+    return events;
+}
+// ─── findForkPoint ───────────────────────────────────────────────────────
+/**
+ * Find the index of the last common event between two logs by comparing hashes.
+ * Returns -1 if the first events differ (completely diverged).
+ * If one log is a prefix of the other, returns length of shorter - 1.
+ */
+export function findForkPoint(logA, logB) {
+    const minLen = Math.min(logA.length, logB.length);
+    let lastCommon = -1;
+    for (let i = 0; i < minLen; i++) {
+        if (logA[i].hash === logB[i].hash) {
+            lastCommon = i;
+        }
+        else {
+            break;
+        }
+    }
+    return lastCommon;
+}
+// ─── compactMilestoneEvents ─────────────────────────────────────────────────
+/**
+ * Archive a milestone's events from the active log to a separate file.
+ * Active log retains only events from other milestones.
+ * Archived file is kept on disk for forensics.
+ *
+ * @param basePath - Project root (parent of .gsd/)
+ * @param milestoneId - The milestone whose events should be archived
+ * @returns { archived: number } — count of events moved to archive
+ */
+export function compactMilestoneEvents(basePath, milestoneId) {
+    const logPath = join(basePath, ".gsd", "event-log.jsonl");
+    const archivePath = join(basePath, ".gsd", `event-log-${milestoneId}.jsonl.archived`);
+    const allEvents = readEvents(logPath);
+    const toArchive = allEvents.filter((e) => e.params.milestoneId === milestoneId);
+    const remaining = allEvents.filter((e) => e.params.milestoneId !== milestoneId);
+    if (toArchive.length === 0) {
+        return { archived: 0 };
+    }
+    // Write archived events to .jsonl.archived file (crash-safe)
+    atomicWriteSync(archivePath, toArchive.map((e) => JSON.stringify(e)).join("\n") + "\n");
+    // Truncate active log to remaining events only
+    atomicWriteSync(logPath, remaining.length > 0
+        ? remaining.map((e) => JSON.stringify(e)).join("\n") + "\n"
+        : "");
+    return { archived: toArchive.length };
+}