pi-crew 0.5.25 → 0.6.1

package/src/runtime/run-drift.ts

@@ -0,0 +1,220 @@
+/**
+ * Runtime drift detectors — detect state anomalies in pi-crew runs.
+ *
+ * Pattern origin: GSD-2 ADR-017 drift detection & state reconciliation.
+ * Each detector checks for a specific anomaly and returns a report.
+ * Repair handlers are idempotent — safe to run multiple times.
+ */
+
+import { existsSync, statSync, readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { logInternalError } from "../utils/internal-error.ts";
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+export type DriftKind =
+	| "stale-process"         // Heartbeat timeout (existing)
+	| "orphaned-claim"        // Task claim without task
+	| "orphaned-worktree"     // Worktree dir without active run
+	| "missing-timestamps"    // State files without timestamps
+	| "status-divergence"     // Manifest status ≠ status file
+	| "unregistered-run";     // State dir but no manifest
+
+export interface DriftReport {
+	kind: DriftKind;
+	runId: string;
+	details: string;
+	repaired: boolean;
+	repairResult?: string;
+}
+
+export interface DriftContext {
+	/** Root directory for crew state (.crew/) */
+	crewRoot: string;
+	/** Active run IDs (from registry) */
+	activeRunIds: Set<string>;
+	/** Manifest content if available */
+	manifest?: { runId: string; status: string; cwd: string; [k: string]: unknown };
+}
+
+// ── Detectors ────────────────────────────────────────────────────────────
+
+/**
+ * Detect task claims that reference tasks not in the manifest.
+ */
+export function detectOrphanedClaim(ctx: DriftContext): DriftReport | null {
+	if (!ctx.manifest) return null;
+	const claimsDir = path.join(ctx.crewRoot, "state", "task-claims");
+	if (!existsSync(claimsDir)) return null;
+
+	const claimFiles = readdirSync(claimsDir).filter((f) => f.endsWith(".json"));
+	for (const file of claimFiles) {
+		try {
+			const claim = JSON.parse(readFileSync(path.join(claimsDir, file), "utf-8"));
+			if (claim.runId === ctx.manifest.runId && claim.taskId) {
+				// Check if task exists in manifest tasks array
+				const tasks = (ctx.manifest as Record<string, unknown>).tasks;
+				if (Array.isArray(tasks) && !tasks.some((t: Record<string, unknown>) => t.id === claim.taskId)) {
+					return {
+						kind: "orphaned-claim",
+						runId: ctx.manifest.runId,
+						details: `Task claim '${claim.taskId}' references non-existent task`,
+						repaired: false,
+					};
+				}
+			}
+		} catch {
+			// Malformed claim file — skip
+		}
+	}
+	return null;
+}
+
+/**
+ * Detect worktree directories that don't belong to any active run.
+ */
+export function detectOrphanedWorktree(ctx: DriftContext): DriftReport | null {
+	const worktreesDir = path.join(ctx.crewRoot, "worktrees");
+	if (!existsSync(worktreesDir)) return null;
+
+	const dirs = readdirSync(worktreesDir, { withFileTypes: true })
+		.filter((d) => d.isDirectory())
+		.map((d) => d.name);
+
+	for (const dir of dirs) {
+		// Extract run ID from worktree dir name (format: <runId>-<taskId> or <runId>)
+		const runId = dir.split("-").slice(0, 5).join("-"); // heuristic: run IDs are timestamp-based
+		if (!ctx.activeRunIds.has(runId) && !ctx.activeRunIds.has(dir)) {
+			return {
+				kind: "orphaned-worktree",
+				runId: dir,
+				details: `Worktree '${dir}' has no active run`,
+				repaired: false,
+			};
+		}
+	}
+	return null;
+}
+
+/**
+ * Detect state files missing required timestamps.
+ */
+export function detectMissingTimestamps(ctx: DriftContext): DriftReport | null {
+	if (!ctx.manifest) return null;
+	const stateDir = path.join(ctx.crewRoot, "state");
+	if (!existsSync(stateDir)) return null;
+
+	// Check manifest has createdAt/updatedAt
+	const m = ctx.manifest as Record<string, unknown>;
+	if (!m.createdAt && !m.updatedAt) {
+		return {
+			kind: "missing-timestamps",
+			runId: ctx.manifest.runId,
+			details: "Manifest missing createdAt/updatedAt timestamps",
+			repaired: false,
+		};
+	}
+	return null;
+}
+
+/**
+ * Detect divergence between manifest status and individual task status files.
+ */
+export function detectStatusDivergence(ctx: DriftContext): DriftReport | null {
+	if (!ctx.manifest) return null;
+	const statusPath = path.join(ctx.crewRoot, "state", `${ctx.manifest.runId}.status`);
+	if (!existsSync(statusPath)) return null;
+
+	try {
+		const status = readFileSync(statusPath, "utf-8").trim();
+		if (status !== ctx.manifest.status) {
+			return {
+				kind: "status-divergence",
+				runId: ctx.manifest.runId,
+				details: `Manifest says '${ctx.manifest.status}' but status file says '${status}'`,
+				repaired: false,
+			};
+		}
+	} catch {
+		// Can't read status file — not drift, might be permissions
+	}
+	return null;
+}
+
+/**
+ * Detect state directories that have no corresponding manifest.
+ */
+export function detectUnregisteredRun(ctx: DriftContext): DriftReport | null {
+	const runsDir = path.join(ctx.crewRoot, "runs");
+	if (!existsSync(runsDir)) return null;
+
+	const runDirs = readdirSync(runsDir, { withFileTypes: true })
+		.filter((d) => d.isDirectory())
+		.map((d) => d.name);
+
+	for (const runId of runDirs) {
+		if (!ctx.activeRunIds.has(runId)) {
+			// Check if it has state files (manifest exists)
+			const manifestPath = path.join(runsDir, runId, "manifest.json");
+			if (existsSync(manifestPath)) {
+				try {
+					const stat = statSync(manifestPath);
+					const ageMs = Date.now() - stat.mtimeMs;
+					// Only flag if older than 1 hour (might be in-progress)
+					if (ageMs > 60 * 60 * 1000) {
+						return {
+							kind: "unregistered-run",
+							runId,
+							details: `Run '${runId}' has manifest but is not in active registry (age: ${Math.round(ageMs / 60000)}m)`,
+							repaired: false,
+						};
+					}
+				} catch {
+					// Can't stat — skip
+				}
+			}
+		}
+	}
+	return null;
+}
+
+// ── Reconciliation Loop ─────────────────────────────────────────────────
+
+const ALL_DETECTORS = [
+	detectOrphanedClaim,
+	detectOrphanedWorktree,
+	detectMissingTimestamps,
+	detectStatusDivergence,
+	detectUnregisteredRun,
+];
+
+/**
+ * Run all drift detectors and collect reports.
+ * Capped at maxPasses repair attempts.
+ *
+ * Pattern origin: GSD-2 ADR-017 — capped at 2 retry passes.
+ */
+export function runDriftDetection(ctx: DriftContext, maxPasses = 2): DriftReport[] {
+	const reports: DriftReport[] = [];
+
+	for (let pass = 0; pass < maxPasses; pass++) {
+		let newFindings = 0;
+
+		for (const detector of ALL_DETECTORS) {
+			try {
+				const report = detector(ctx);
+				if (report) {
+					reports.push(report);
+					newFindings++;
+				}
+			} catch (error) {
+				logInternalError("run-drift", error, `detector=${detector.name} runId=${ctx.manifest?.runId}`);
+			}
+		}
+
+		// If no new findings, stop early
+		if (newFindings === 0) break;
+	}
+
+	return reports;
+}

package/src/runtime/sandbox.ts

@@ -21,28 +21,32 @@ const FORBIDDEN_PATTERNS = [
 	// Global escape vectors
 	/\bglobalThis\b/,                 // globalThis reference
 	/\bglobal\b/,                      // global reference (Node.js)
+	/\bconstructor\b/,                 // Block constructor chain escape: [].constructor.constructor("return process")()
 ] as const;
 
+Object.freeze(FORBIDDEN_PATTERNS);
+
 /**
- * Whitelist of allowed identifiers for strict mode.
- * Only these identifiers can be used in sandboxed code.
+ * SECURITY (HIGH #3 fix): Normalize source code before forbidden-pattern checks
+ * to prevent unicode-escape bypasses.
+ *
+ * Attackers can write `import\u0028"fs"\u0029` which compiles as
+ * `import("fs")` but does not match the regex `/import\s*\(/`.
+ *
+ * This function:
+ * 1. Strips null bytes (used to split keywords across boundaries)
+ * 2. Decodes \uXXXX escape sequences so regexes see the actual characters
  */
-const ALLOWED_IDENTIFIERS = new Set([
-	// Built-in constructors
-	"Array", "Boolean", "Date", "Error", "Function", "JSON", "Map", "Number", "Object", "Promise", "RegExp", "Set", "String", "Symbol",
-	// Static methods
-	"ArrayBuffer", "Uint8Array", "parseInt", "parseFloat", "isNaN", "isFinite",
-	// URI encoding
-	"encodeURI", "decodeURI", "encodeURIComponent", "decodeURIComponent",
-	// Math (read-only)
-	"Math",
-	// Console (safe methods only)
-	"console",
-	// Process (limited)
-	"process",
-]);
-
-Object.freeze(FORBIDDEN_PATTERNS);
+export function normalizeCodeForValidation(code: string): string {
+	// Strip null bytes
+	let normalized = code.replace(/\0/g, "");
+	// Decode common unicode escapes: \u0028 → (
+	normalized = normalized.replace(
+		/\\u([0-9a-fA-F]{4})/g,
+		(_, hex) => String.fromCharCode(Number.parseInt(hex, 16)),
+	);
+	return normalized;
+}
 
 export interface SandboxOptions {
 	timeout?: number;
@@ -204,15 +208,17 @@ export class WorkflowSandbox {
 	 * ensure compilation is safe.
 	 */
 	private validateScript(code: string): void {
+		// SECURITY (HIGH #3 fix): Normalize unicode escapes before pattern matching
+		const normalized = normalizeCodeForValidation(code);
 		// Check for ESM/module patterns
 		for (const pattern of FORBIDDEN_PATTERNS) {
-			if (pattern.test(code)) {
+			if (pattern.test(normalized)) {
 				throw new Error(`Forbidden pattern detected: ${pattern.source}`);
 			}
 		}
 
 		// Check for import.meta specifically (C4)
-		if (/import\.meta/.test(code)) {
+		if (/import\.meta/.test(normalized)) {
 			throw new Error("import.meta is not allowed in sandboxed code");
 		}
 

package/src/runtime/semaphore.ts

@@ -88,7 +88,8 @@ export interface ParallelResult<R> {
  *
  * Adapted from oh-my-pi's `mapWithConcurrencyLimit`.
  */
-export async function mapWithFailFast<T, R>(
+/** @internal */
+async function mapWithFailFast<T, R>(
 	items: T[],
 	concurrency: number,
 	fn: (item: T, index: number, signal: AbortSignal) => Promise<R>,

package/src/runtime/settings-store.ts

@@ -20,6 +20,18 @@ const MAX_TURNS_CEILING = 10_000;
 const GRACE_TURNS_CEILING = 1_000;
 const VALID_JOIN_MODES = new Set<JoinMode>(["async", "group", "smart"]);
 
+/**
+ * M2: Validate that a scheduled job object has required fields before passing to scheduler.
+ * Prevents opaque unknown[] from reaching CrewScheduler.add() without validation.
+ */
+function validateScheduledJob(job: unknown): boolean {
+	if (!job || typeof job !== "object") return false;
+	const obj = job as Record<string, unknown>;
+	return typeof obj.id === "string" && obj.id.length > 0
+		&& typeof obj.scheduleType === "string"
+		&& typeof obj.enabled === "boolean";
+}
+
 function sanitizeSettings(raw: unknown): CrewSettings {
 	if (!raw || typeof raw !== "object") return {};
 	const r = raw as Record<string, unknown>;
@@ -57,9 +69,9 @@ function sanitizeSettings(raw: unknown): CrewSettings {
 	if (typeof r.notifierIntervalMs === "number" && r.notifierIntervalMs >= 1000) {
 		out.notifierIntervalMs = r.notifierIntervalMs;
 	}
-	// Pass through scheduledJobs as opaque array (validated by crewScheduler.add)
+	// Pass through scheduledJobs after basic validation
 	if (Array.isArray(r.scheduledJobs)) {
-		out.scheduledJobs = r.scheduledJobs;
+		out.scheduledJobs = (r.scheduledJobs as unknown[]).filter(validateScheduledJob);
 	}
 	return out;
 }

package/src/runtime/skill-effectiveness.ts

@@ -374,7 +374,8 @@ export function getWeightedSkillsForRole(
  * Filter skills by confidence threshold.
  * Skills below threshold are marked as "suggest" only.
  */
-export function filterSkillsByConfidence(
+/** @internal */
+function filterSkillsByConfidence(
 	skillIds: string[],
 	runId: string,
 	threshold: keyof typeof CONFIDENCE_THRESHOLDS = "MODERATE",
@@ -431,7 +432,8 @@ export function registerSkillEffectivenessHooks(): void {
 /**
  * Generate a skill effectiveness report for a run.
  */
-export function generateSkillEffectivenessReport(
+/** @internal */
+function generateSkillEffectivenessReport(
 	runId: string,
 	skillIds: string[],
 ): string {

package/src/runtime/skill-instructions.ts

@@ -244,7 +244,10 @@ export function renderSkillInstructions(input: RenderSkillInstructionsInput & {
 		const confidenceNote = weighted ? ` [Confidence: ${(weighted.confidence * 100).toFixed(0)}% — ${weighted.threshold}]` : "";
 
 		const header = [`## ${safeName}`, description ? `Description: ${description}${confidenceNote}` : undefined, `Source: ${source}`].filter(Boolean).join("\n");
-		const section = `${header}\n\n${compactSkillContent(loaded.content)}`;
+		const rawContent = compactSkillContent(loaded.content);
+		// Wrap skill content with provenance markers to help LLMs distinguish skill instructions
+		const wrappedContent = `<!-- skill: ${safeName} -->\n${rawContent}\n<!-- end-skill: ${safeName} -->`;
+		const section = `${header}\n\n${wrappedContent}`;
 		if (!pushSection(section)) omittedCount += 1;
 	}
 	if (omittedCount > 0) {

package/src/runtime/subagent-manager.ts

@@ -88,10 +88,28 @@ export function savePersistedSubagentRecord(cwd: string, record: SubagentRecord)
 	}
 }
 
+const ALLOWED_RECORD_FIELDS = new Set([
+	"agentId", "agentName", "subagentType", "status", "spawnedAt",
+	"completedAt", "model", "runId", "cwd", "taskId", "taskId",
+]);
+
+function sanitizePersistedRecord(raw: unknown): SubagentRecord | undefined {
+	if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+	const obj = raw as Record<string, unknown>;
+	if (typeof obj.agentId !== "string" || !obj.agentId) return undefined;
+	const clean: Record<string, unknown> = { agentId: obj.agentId };
+	for (const key of Object.keys(obj)) {
+		if (ALLOWED_RECORD_FIELDS.has(key) && (typeof obj[key] === "string" || typeof obj[key] === "number" || typeof obj[key] === "boolean")) {
+			clean[key] = obj[key];
+		}
+	}
+	return clean as unknown as SubagentRecord;
+}
+
 export function readPersistedSubagentRecord(cwd: string, id: string): SubagentRecord | undefined {
 	try {
-		const parsed = JSON.parse(fs.readFileSync(persistedSubagentPath(cwd, id), "utf-8"));
-		return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed as SubagentRecord : undefined;
+		const raw = JSON.parse(fs.readFileSync(persistedSubagentPath(cwd, id), "utf-8"));
+		return sanitizePersistedRecord(raw);
 	} catch {
 		return undefined;
 	}

package/src/runtime/subprocess-tool-registry.ts

@@ -61,7 +61,7 @@ class SubprocessToolRegistryImpl implements SubprocessToolRegistry {
 
 export const subprocessToolRegistry: SubprocessToolRegistry = new SubprocessToolRegistryImpl();
 
-/** H3: Reset the global singleton registry (for test isolation). */
-export function resetSubprocessToolRegistry(): void {
+/** @internal Reset the global singleton registry (for test isolation). */
+function resetSubprocessToolRegistry(): void {
 	subprocessToolRegistry.clear();
 }

package/src/runtime/task-graph.ts

@@ -215,3 +215,82 @@ export function detectCycles(tasks: TaskNode[]): string[][] {
 
 	return cycles;
 }
+
+/**
+ * Find tasks that are blocked (not completed, have incomplete dependencies).
+ *
+ * Pattern origin: pi-blueprint dependency-graph.ts findBlockedTasks()
+ *
+ * @param tasks - All task nodes
+ * @param completedIds - Set of completed task IDs
+ * @returns Array of blocked task IDs
+ */
+export function findBlockedTasks(tasks: TaskNode[], completedIds: Set<string>): string[] {
+	return tasks
+		.filter((t) => !completedIds.has(t.id))
+		.filter((t) => t.dependsOn.some((dep) => !completedIds.has(dep)))
+		.map((t) => t.id);
+}
+
+/**
+ * Get specific incomplete dependencies blocking a task.
+ *
+ * Pattern origin: pi-blueprint dependency-graph.ts getBlockingTasks()
+ *
+ * @param tasks - All task nodes
+ * @param taskId - The task to check
+ * @param completedIds - Set of completed task IDs
+ * @returns Array of blocking task IDs
+ */
+export function getBlockingTasks(tasks: TaskNode[], taskId: string, completedIds: Set<string>): string[] {
+	const task = tasks.find((t) => t.id === taskId);
+	if (!task) return [];
+	return task.dependsOn.filter((dep) => !completedIds.has(dep));
+}
+
+/**
+ * Topological sort using Kahn's BFS algorithm.
+ *
+ * Pattern origin: pi-blueprint dependency-graph.ts topologicalSort()
+ *
+ * @param tasks - All task nodes
+ * @returns Ordered array of task IDs (dependencies first)
+ */
+export function topologicalSort(tasks: TaskNode[]): string[] {
+	if (tasks.length === 0) return [];
+
+	const idSet = new Set(tasks.map((t) => t.id));
+	const inDegree = new Map<string, number>();
+	const adjacency = new Map<string, string[]>();
+
+	for (const task of tasks) {
+		inDegree.set(task.id, 0);
+		adjacency.set(task.id, []);
+	}
+
+	for (const task of tasks) {
+		for (const dep of task.dependsOn) {
+			if (!idSet.has(dep)) continue;
+			adjacency.get(dep)!.push(task.id);
+			inDegree.set(task.id, (inDegree.get(task.id) ?? 0) + 1);
+		}
+	}
+
+	const queue: string[] = [];
+	for (const [id, deg] of inDegree) {
+		if (deg === 0) queue.push(id);
+	}
+
+	const result: string[] = [];
+	while (queue.length > 0) {
+		const id = queue.shift()!;
+		result.push(id);
+		for (const dependent of adjacency.get(id) ?? []) {
+			const deg = inDegree.get(dependent)! - 1;
+			inDegree.set(dependent, deg);
+			if (deg === 0) queue.push(dependent);
+		}
+	}
+
+	return result;
+}

package/src/runtime/task-id.ts

@@ -0,0 +1,148 @@
+/**
+ * Hash-based task ID generation with adaptive length and hierarchical decomposition.
+ *
+ * Pattern origin: beads/internal/idgen/hash.go — SHA-256 → base36 encoding
+ * with birthday-paradox collision probability adaptation.
+ *
+ * IDs look like: `pc-a1b2` (prefix + base36 hash)
+ * Hierarchical: `pc-a1b2.1` (parent.child)
+ */
+
+import { createHash } from "node:crypto";
+
+// ── Configuration ────────────────────────────────────────────────────────
+
+const DEFAULT_PREFIX = "pc";
+const BASE36_CHARS = "0123456789abcdefghijklmnopqrstuvwxyz";
+
+interface AdaptiveIDConfig {
+	maxCollisionProbability: number;
+	minLength: number;
+	maxLength: number;
+}
+
+const DEFAULT_CONFIG: AdaptiveIDConfig = {
+	maxCollisionProbability: 0.25,
+	minLength: 3,
+	maxLength: 8,
+};
+
+// ── Core Functions ───────────────────────────────────────────────────────
+
+/**
+ * Generate a hash-based ID using SHA-256 → base36 encoding.
+ *
+ * @param content - String content to hash
+ * @param length - Desired hash length (3–8 chars)
+ * @returns Base36 hash string
+ */
+export function hashToBase36(content: string, length: number): string {
+	const hash = createHash("sha256").update(content).digest();
+	let result = "";
+	for (let i = 0; i < hash.length && result.length < length; i++) {
+		const byte = hash[i]!;
+		// Use modulo to map byte to base36
+		result += BASE36_CHARS[byte % 36]!;
+	}
+	return result.padEnd(length, "0").slice(0, length);
+}
+
+/**
+ * Calculate adaptive hash length based on existing ID count.
+ *
+ * Uses birthday-paradox formula: P(collision) ≈ 1 - e^(-n² / (2 * 36^L))
+ *
+ * @param existingCount - Number of existing IDs with the same prefix
+ * @param config - Adaptive configuration
+ * @returns Recommended hash length
+ */
+export function calculateAdaptiveLength(
+	existingCount: number,
+	config: AdaptiveIDConfig = DEFAULT_CONFIG,
+): number {
+	for (let length = config.minLength; length <= config.maxLength; length++) {
+		const totalPossibilities = Math.pow(36, length);
+		const probability = 1 - Math.exp(-(existingCount * existingCount) / (2 * totalPossibilities));
+		if (probability <= config.maxCollisionProbability) {
+			return length;
+		}
+	}
+	return config.maxLength;
+}
+
+/**
+ * Generate a deterministic hash-based task ID.
+ *
+ * @param parts - Content parts to hash (title, description, etc.)
+ * @param prefix - ID prefix (default: "pc")
+ * @param existingCount - Number of existing IDs (for adaptive length)
+ * @returns Hash-based ID like "pc-a1b2"
+ */
+export function generateTaskHashId(
+	parts: string[],
+	prefix = DEFAULT_PREFIX,
+	existingCount = 0,
+): string {
+	const content = parts.join("|");
+	const length = calculateAdaptiveLength(existingCount);
+	const hash = hashToBase36(content, length);
+	return `${prefix}-${hash}`;
+}
+
+// ── Hierarchical IDs ────────────────────────────────────────────────────
+
+export interface ParsedHierarchicalId {
+	parentId: string;
+	childNum: number;
+	isHierarchical: boolean;
+}
+
+/**
+ * Parse a hierarchical ID into parent and child number.
+ *
+ * Example: "pc-a1b2.3" → { parentId: "pc-a1b2", childNum: 3, isHierarchical: true }
+ */
+export function parseHierarchicalId(id: string): ParsedHierarchicalId {
+	const dotIndex = id.lastIndexOf(".");
+	if (dotIndex === -1 || dotIndex < 3) {
+		return { parentId: id, childNum: 0, isHierarchical: false };
+	}
+
+	const parentId = id.slice(0, dotIndex);
+	const childStr = id.slice(dotIndex + 1);
+	const childNum = Number.parseInt(childStr, 10);
+
+	if (!Number.isFinite(childNum) || childNum < 1) {
+		return { parentId: id, childNum: 0, isHierarchical: false };
+	}
+
+	return { parentId, childNum, isHierarchical: true };
+}
+
+/**
+ * Generate a child ID from a parent ID and child number.
+ *
+ * Example: childId("pc-a1b2", 3) → "pc-a1b2.3"
+ */
+export function childId(parentId: string, childNum: number): string {
+	return `${parentId}.${childNum}`;
+}
+
+// ── Dependency Types ─────────────────────────────────────────────────────
+
+/**
+ * Rich dependency types for task relationships.
+ *
+ * Pattern origin: beads/internal/types/types.go — 19 DependencyType constants
+ * Only "blocks" and "parent-child" affect execution ordering.
+ */
+export type DependencyType =
+	| "blocks"              // A must complete before B starts
+	| "parent-child"        // Hierarchical relationship
+	| "conditional-blocks"  // B runs only if A fails
+	| "waits-for"           // Fanout gate: wait for dynamic children
+	| "related"             // Association only (no ordering)
+	| "supersedes"          // A replaces B
+	| "duplicates"          // A duplicates B
+	| "delegated-from"      // A was delegated from B
+	| "validates";          // A validates B's output

package/src/runtime/task-packet.ts

@@ -1,6 +1,7 @@
 import * as path from "node:path";
 import type { TeamRunManifest, TaskPacket, TaskScope, VerificationContract } from "../state/types.ts";
 import type { WorkflowStep } from "../workflows/workflow-config.ts";
+import { generateTaskHashId } from "./task-id.ts";
 
 // ═══════════════════════════════════════════════════════════════════════════
 // SEC-007 Fix: Workflow Step Task Sanitization
@@ -81,8 +82,19 @@ export function buildTaskPacket(input: BuildTaskPacketInput): TaskPacket {
 	const scopePath = reads.length === 1 ? reads[0] : reads.length > 1 ? reads.join(", ") : undefined;
 	// SEC-007: Sanitize task text before inserting into task packet
 	const sanitizedTask = sanitizeTaskText(input.step.task);
+	const sanitizedGoal = sanitizeTaskText(input.manifest.goal);
+
+	// Generate a deterministic hash-based task ID for traceability and logging.
+	// Uses goal + step ID + run ID as content parts.
+	// TODO: Once TaskPacket type gains a hashId field, include this in the packet.
+	const _taskHashId = generateTaskHashId([
+		input.manifest.goal,
+		input.step.id,
+		input.manifest.runId,
+	]);
+
 	return {
-		objective: sanitizedTask.replaceAll("{goal}", input.manifest.goal),
+		objective: sanitizedTask.replaceAll("{goal}", sanitizedGoal),
 		scope,
 		scopePath,
 		repo: path.basename(input.manifest.cwd) || input.manifest.cwd,