@gajae-code/coding-agent 0.5.0 → 0.5.2

package/src/gjc-runtime/state-writer.ts

@@ -1,6 +1,8 @@
 import { createHash, randomUUID } from "node:crypto";
+import type { Stats } from "node:fs";
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
+import { type FileLockOptions, withFileLock } from "../config/file-lock";
 import type { ActiveSubskillEntry, SkillActiveEntry, SkillActiveState } from "../skill-state/active-state";
 import {
 	type AuditEntry,
@@ -80,6 +82,12 @@ export interface StateWriterOptions {
 	cwd?: string;
 	receipt?: StateWriterReceiptContext;
 	audit?: StateWriterAuditContext;
+	/**
+	 * Cross-process lock tuning for read-modify-write paths that route through
+	 * `withWorkflowStateLock` / `updateJsonAtomic`. Omit for the hardened
+	 * `withFileLock` defaults.
+	 */
+	lock?: FileLockOptions;
 }
 
 export interface DeleteIfOwnedOptions extends StateWriterOptions {
@@ -113,7 +121,7 @@ export interface GenericHardPruneTarget {
 export interface GenericHardPruneSelectorContext {
 	path: string;
 	category: WriterCategory | string;
-	stat: Awaited<ReturnType<typeof fs.stat>>;
+	stat: Stats;
 	readJson: () => Promise<unknown>;
 }
 
@@ -388,6 +396,57 @@ export async function writeJsonAtomic(
 	return filePath;
 }
 
+async function readPersistedPhase(filePath: string): Promise<string | undefined> {
+	try {
+		const existing = await readJsonIfPresent(filePath);
+		if (!isPlainObject(existing)) return undefined;
+		// Only an *active* prior envelope is a transition source. A cleared / handed-off
+		// envelope (`active: false`, terminal phase such as `complete` / `handoff`) is outside
+		// active workflow progression, so reactivation from it (e.g. a fresh kickoff) must not
+		// be reported as an invalid transition.
+		if (existing.active !== true) return undefined;
+		const phase = existing.current_phase;
+		return typeof phase === "string" ? phase : undefined;
+	} catch {
+		// Best-effort diagnostic read: a corrupt/unreadable prior envelope simply yields no
+		// `from` phase, so the transition invariant degrades to a no-op rather than failing
+		// the sanctioned write it is observing.
+		return undefined;
+	}
+}
+
+async function recordInvalidWorkflowTransition(args: {
+	filePath: string;
+	skill: CanonicalGjcWorkflowSkill;
+	fromPhase: string;
+	toPhase: string;
+	options?: StateWriterOptions;
+}): Promise<void> {
+	const { filePath, skill, fromPhase, toPhase, options } = args;
+	// Audit-only diagnostic: a successful sanctioned write must NOT emit to stderr — callers
+	// may treat any stderr output as failure or parse stdout/stderr as machine output. The
+	// `invalid_transition_detected` audit entry is the durable, non-intrusive evidence that an
+	// internal write skipped a manifest edge.
+	const cwd = path.resolve(options?.audit?.cwd ?? options?.cwd ?? process.cwd());
+	try {
+		await appendAuditEntry(cwd, {
+			ts: new Date().toISOString(),
+			skill,
+			category: "state",
+			verb: "invalid_transition_detected",
+			owner: options?.audit?.owner ?? "gjc-runtime",
+			mutation_id: options?.audit?.mutationId ?? `${skill}:invalid-transition:${new Date().toISOString()}`,
+			from_phase: fromPhase,
+			to_phase: toPhase,
+			forced: false,
+			paths: [filePath],
+		});
+	} catch {
+		// Audit logging is best-effort diagnostics; never fail a sanctioned write because the
+		// audit append failed (e.g. cwd is not a writable project root).
+	}
+}
+
 export async function writeWorkflowEnvelopeAtomic(
 	targetPath: string,
 	value: unknown,
@@ -404,6 +463,50 @@ export async function writeWorkflowEnvelopeAtomic(
 				.join("; ")}`,
 		);
 	}
+	// #658: internal runtime writers (ralplan/ultragoal/deep-interview/team) persist
+	// envelopes directly, bypassing the `gjc state` CLI transition gate (`isValidTransition`,
+	// historically the sole call site in state-runtime.ts). Re-assert that gate on every
+	// sanctioned envelope write so internal writes cannot persist invalid state-machine phase
+	// transitions silently. Forced writes (`gjc state ... --force`, reconcile repairs) carry
+	// `audit.forced` and bypass, mirroring the CLI's `use --force to bypass`.
+	//
+	// The gate governs ACTIVE workflow progression only. Deactivation/teardown writes
+	// (`active: false`, e.g. `gjc state clear`, which persists the universal `complete`
+	// sentinel that is not a per-skill manifest state) leave the transition graph and are
+	// intentionally exempt.
+	if (options?.audit?.forced !== true && parsed.data.active === true) {
+		const toPhase = parsed.data.current_phase.trim();
+		if (toPhase) {
+			// Lazy import: workflow-manifest dereferences CANONICAL_GJC_WORKFLOW_SKILLS at
+			// module load, and active-state -> state-writer -> workflow-manifest -> active-state
+			// is a load-time cycle. Importing at call time (after init) avoids the TDZ.
+			const { isKnownWorkflowState, isValidTransition } = await import("./workflow-manifest");
+			const skill = parsed.data.skill;
+			// Structural invariant (hard): a `current_phase` absent from the skill's manifest is
+			// never a legitimate internal write, matching the CLI/reconcile unknown-phase gate.
+			if (!isKnownWorkflowState(skill, toPhase)) {
+				throw new Error(
+					`Refusing to write unknown ${skill} phase "${toPhase}" to ${filePath}: not a known ${skill} manifest state (forced writes bypass via audit.forced)`,
+				);
+			}
+			// Transition invariant (#658, diagnostic-only safety net): resolve the prior phase
+			// (caller-supplied `audit.fromPhase`, else the active persisted envelope on disk) and
+			// flag edges the manifest does not define. Intentionally NON-blocking and audit-only
+			// — the CLI path already hard-fails invalid edges before reaching here, and legitimate
+			// internal repairs / ralplan short-mode stage skips move between valid states without a
+			// direct manifest edge. It records an `invalid_transition_detected` audit entry (no
+			// stderr) so such transitions are non-silent without breaking those flows.
+			const fromPhase = (options?.audit?.fromPhase ?? (await readPersistedPhase(filePath)))?.trim();
+			if (
+				fromPhase &&
+				fromPhase !== toPhase &&
+				isKnownWorkflowState(skill, fromPhase) &&
+				!isValidTransition(skill, fromPhase, toPhase)
+			) {
+				await recordInvalidWorkflowTransition({ filePath, skill, fromPhase, toPhase, options });
+			}
+		}
+	}
 	await atomicWrite(filePath, jsonText(stamped));
 	await maybeAudit(filePath, options);
 	return filePath;
@@ -416,17 +519,55 @@ export async function writeTextAtomic(targetPath: string, text: string, options?
 	return filePath;
 }
 
+/**
+ * Serialize a read-modify-write (or any multi-step mutation) against concurrent
+ * writers of the same `.gjc/**` target. Uses the cross-process directory lock
+ * from `withFileLock`, keyed on the resolved file path, so separate CLI/agent
+ * processes (e.g. team-mode workers) cannot interleave one writer's read with
+ * another writer's write and silently drop the first mutation (issue #646).
+ *
+ * The lock is advisory: it only protects callers that route through it, so every
+ * read-modify-write of a given file MUST acquire this lock for the same resolved
+ * path. `atomicWrite`'s temp-file + rename crash-atomicity is preserved; this
+ * layers concurrency-atomicity on top without weakening it.
+ */
+export async function withWorkflowStateLock<T>(
+	targetPath: string,
+	fn: () => Promise<T>,
+	options?: StateWriterOptions,
+): Promise<T> {
+	const filePath = resolveGjcTarget(targetPath, cwdForOptions(options));
+	return lockResolvedWorkflowTarget(filePath, fn, options?.lock);
+}
+
+async function lockResolvedWorkflowTarget<T>(
+	filePath: string,
+	fn: () => Promise<T>,
+	lockOptions?: FileLockOptions,
+): Promise<T> {
+	// `withFileLock` creates the lock dir next to the target with a non-recursive
+	// mkdir, so the parent directory must exist before the lock is acquired.
+	await fs.mkdir(path.dirname(filePath), { recursive: true });
+	return withFileLock(filePath, fn, lockOptions);
+}
+
 export async function updateJsonAtomic<T = unknown>(
 	targetPath: string,
 	mutator: (current: T | undefined) => T | Promise<T>,
 	options?: StateWriterOptions,
 ): Promise<string> {
 	const filePath = resolveGjcTarget(targetPath, cwdForOptions(options));
-	const current = (await readJsonIfPresent(filePath)) as T | undefined;
-	const next = await mutator(current);
-	await atomicWrite(filePath, jsonText(withWorkflowReceipt(next, buildReceipt(options))));
-	await maybeAudit(filePath, options);
-	return filePath;
+	return lockResolvedWorkflowTarget(
+		filePath,
+		async () => {
+			const current = (await readJsonIfPresent(filePath)) as T | undefined;
+			const next = await mutator(current);
+			await atomicWrite(filePath, jsonText(withWorkflowReceipt(next, buildReceipt(options))));
+			await maybeAudit(filePath, options);
+			return filePath;
+		},
+		options?.lock,
+	);
 }
 
 export async function appendJsonl(targetPath: string, entry: unknown, options?: StateWriterOptions): Promise<string> {
@@ -437,6 +578,112 @@ export async function appendJsonl(targetPath: string, entry: unknown, options?:
 	return filePath;
 }
 
+export interface AppendJsonlIdempotentOptions extends StateWriterOptions {
+	/**
+	 * Identity key for an entry. Two entries that produce the same non-`undefined`
+	 * key are duplicates, so only the first is appended. Return `undefined` to opt a
+	 * candidate out of dedup (it is always appended). Use `key` for the common case
+	 * where identity reduces to a single string.
+	 */
+	key?: (entry: unknown) => string | undefined;
+	/**
+	 * Equivalence predicate: return `true` when `existing` already represents
+	 * `candidate`, suppressing the append. Use when identity cannot be reduced to a
+	 * single string key. When both `key` and `equals` are supplied, `equals` wins.
+	 */
+	equals?: (candidate: unknown, existing: unknown) => boolean;
+}
+
+export interface AppendJsonlIdempotentResult {
+	path: string;
+	/** `true` when the entry was written; `false` when an equivalent entry already existed. */
+	appended: boolean;
+	/** The pre-existing entry that suppressed the append, when `appended` is `false`. */
+	duplicate?: unknown;
+}
+
+async function readJsonlEntries(filePath: string): Promise<unknown[]> {
+	let raw: string;
+	try {
+		raw = await fs.readFile(filePath, "utf-8");
+	} catch (error) {
+		if (isErrno(error, "ENOENT")) return [];
+		throw error;
+	}
+	const entries: unknown[] = [];
+	for (const line of raw.split(/\r?\n/)) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		try {
+			entries.push(JSON.parse(trimmed));
+		} catch {
+			// Best-effort: dedup compares parseable rows only. A corrupt line cannot
+			// be matched, so it never suppresses a new append.
+		}
+	}
+	return entries;
+}
+
+function findJsonlDuplicate(
+	existing: readonly unknown[],
+	candidate: unknown,
+	options: AppendJsonlIdempotentOptions,
+): unknown | undefined {
+	if (options.equals) {
+		const equals = options.equals;
+		return existing.find(item => equals(candidate, item));
+	}
+	const key = options.key;
+	if (!key) return undefined;
+	const candidateKey = key(candidate);
+	if (candidateKey === undefined) return undefined;
+	return existing.find(item => key(item) === candidateKey);
+}
+
+/**
+ * Append `entry` to a JSONL file only when no equivalent entry already exists —
+ * the shared idempotent append primitive (issue #660).
+ *
+ * `appendJsonl` is a pure append with no dedup, so every recurring "duplicate
+ * ledger row" bug (#638, #643, #645) had to be patched with bespoke per-call-site
+ * guards. This primitive centralizes the read-check-append cycle: a caller
+ * declares identity once via `key` or `equals` instead of re-deriving the lookup
+ * at each site.
+ *
+ * The read-then-append is serialized through the same cross-process workflow lock
+ * as `updateJsonAtomic`, so two concurrent idempotent appends cannot both observe
+ * "no duplicate" and both write (the #646 TOCTOU that a plain `appendJsonl`
+ * preceded by a manual existence check is still exposed to).
+ *
+ * Scope note: this dedups the *append* only. Call sites whose idempotency must
+ * also skip a coupled mutation — e.g. the plan/state rewrite in #643/#645 — still
+ * need a whole-operation guard; this primitive is the ledger-level half of that.
+ */
+export async function appendJsonlIdempotent(
+	targetPath: string,
+	entry: unknown,
+	options: AppendJsonlIdempotentOptions,
+): Promise<AppendJsonlIdempotentResult> {
+	if (!options.key && !options.equals) {
+		throw new Error("appendJsonlIdempotent requires a `key` or `equals` option to detect duplicates");
+	}
+	const filePath = resolveGjcTarget(targetPath, cwdForOptions(options));
+	return lockResolvedWorkflowTarget(
+		filePath,
+		async () => {
+			const existing = await readJsonlEntries(filePath);
+			const duplicate = findJsonlDuplicate(existing, entry, options);
+			if (duplicate !== undefined) {
+				return { path: filePath, appended: false, duplicate };
+			}
+			await fs.appendFile(filePath, `${JSON.stringify(entry)}\n`, "utf-8");
+			await maybeAudit(filePath, options);
+			return { path: filePath, appended: true };
+		},
+		options.lock,
+	);
+}
+
 export async function appendText(targetPath: string, text: string, options?: StateWriterOptions): Promise<string> {
 	const filePath = resolveGjcTarget(targetPath, cwdForOptions(options));
 	await fs.mkdir(path.dirname(filePath), { recursive: true });
@@ -639,7 +886,7 @@ export async function hardPrune(
 	const removed: string[] = [];
 	for (const target of targets) {
 		const filePath = resolveGjcTarget(target.path, cwd);
-		let stat: Awaited<ReturnType<typeof fs.stat>>;
+		let stat: Stats;
 		try {
 			stat = await fs.stat(filePath);
 		} catch (error) {

package/src/gjc-runtime/team-gc.ts

@@ -0,0 +1,49 @@
+/**
+ * GC adapter for team workers (`.gjc/state/team/<name>/workers/<id>/` heartbeat
+ * + lifecycle). Liveness-only: numeric PID status dominates lifecycle/heartbeat
+ * signals.
+ */
+
+import * as path from "node:path";
+import { listHarnessRootRegistriesForGc } from "../harness-control-plane/storage";
+import type { GcCollectResult, GcContext, GcPruneOutcome, GcRecord, GcStoreAdapter } from "./gc-runtime";
+import { listTeamWorkerGcRecords, pruneTeamWorkerGcRecord } from "./team-runtime";
+
+function uniqueTeamRootsFromHarnessRoots(roots: string[]): string[] {
+	return [...new Set(roots.map(root => path.join(path.dirname(root), "team")))].sort();
+}
+
+export const teamWorkersGcAdapter: GcStoreAdapter = {
+	store: "team_workers",
+	async collect(ctx: GcContext): Promise<GcCollectResult> {
+		const records: GcRecord[] = [];
+		const errors: GcCollectResult["errors"] = [];
+		const registries = await listHarnessRootRegistriesForGc(ctx.env);
+		for (const registry of registries) {
+			if (registry.error) errors.push({ store: "team_workers", scope: registry.file, message: registry.error });
+		}
+
+		const teamRoots = uniqueTeamRootsFromHarnessRoots(
+			registries.flatMap(registry => registry.roots.map(entry => entry.root)),
+		);
+		for (const teamRoot of teamRoots) {
+			try {
+				records.push(...(await listTeamWorkerGcRecords(teamRoot, ctx.probe)));
+			} catch (error) {
+				const code = (error as NodeJS.ErrnoException).code;
+				if (code === "ENOENT") continue;
+				errors.push({ store: "team_workers", scope: teamRoot, message: (error as Error).message });
+			}
+		}
+
+		return { records, errors };
+	},
+	async prune(record: GcRecord, ctx: GcContext): Promise<GcPruneOutcome> {
+		try {
+			const removed = await pruneTeamWorkerGcRecord(record, ctx.probe);
+			return removed ? { removed: true } : { removed: false, skipped: "worker_no_longer_dead" };
+		} catch (error) {
+			return { removed: false, error: (error as Error).message };
+		}
+	},
+};

package/src/gjc-runtime/team-runtime.ts

@@ -4,6 +4,7 @@ import * as path from "node:path";
 import type { WorkflowHudSummary } from "../skill-state/active-state";
 import { buildTeamHudSummary as buildWorkflowTeamHudSummary } from "../skill-state/workflow-hud";
 import { WORKFLOW_STATE_VERSION } from "../skill-state/workflow-state-contract";
+import type { GcPidProbe, GcRecord } from "./gc-runtime";
 
 import { applyGjcTmuxProfile, GJC_TMUX_LAUNCHED_ENV } from "./launch-tmux";
 import {
@@ -18,6 +19,7 @@ import {
 	writeWorkflowEnvelopeAtomic,
 } from "./state-writer";
 import {
+	buildGjcTmuxExactOptionTarget,
 	buildGjcTmuxUntaggedSessionHint,
 	GJC_TMUX_PROFILE_OPTION,
 	GJC_TMUX_PROFILE_VALUE,
@@ -677,6 +679,174 @@ async function readJsonFile<T>(filePath: string): Promise<T | null> {
 		throw error;
 	}
 }
+function isPositivePid(value: unknown): value is number {
+	return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+
+function collectTeamGcWorkerPids(
+	heartbeat: WorkerHeartbeatFile | null,
+	lifecycle: GjcTeamWorkerLifecycle | null,
+): number[] {
+	const pids: number[] = [];
+	if (isPositivePid(heartbeat?.pid)) pids.push(heartbeat.pid);
+	if (isPositivePid(lifecycle?.pid) && !pids.includes(lifecycle.pid)) pids.push(lifecycle.pid);
+	return pids;
+}
+
+interface TeamGcPidClassification {
+	removable: boolean;
+	pidStatus: "dead" | "alive" | "eperm" | "unknown" | "none";
+	pid?: number;
+}
+
+/**
+ * Liveness-only, fail-closed: a worker is removable ONLY when it has at least
+ * one authoritative pid and EVERY candidate pid probes dead (ESRCH). Any alive,
+ * EPERM, or unknown candidate (heartbeat OR lifecycle) keeps the worker, so a
+ * dead heartbeat pid can never override a live lifecycle pid.
+ */
+function classifyTeamGcWorkerPids(pids: number[], probe: GcPidProbe): TeamGcPidClassification {
+	if (pids.length === 0) return { removable: false, pidStatus: "none" };
+	const statuses = pids.map(pid => ({ pid, status: gcProbeStatus(probe, pid) }));
+	const kept = statuses.find(entry => entry.status !== "dead");
+	if (kept) return { removable: false, pidStatus: kept.status, pid: kept.pid };
+	return { removable: true, pidStatus: "dead", pid: statuses[0]?.pid };
+}
+
+function gcProbeStatus(probe: GcPidProbe, pid: number): "dead" | "alive" | "eperm" | "unknown" {
+	const result = probe(pid);
+	if (result.status === "dead") return "dead";
+	return result.reason ?? "unknown";
+}
+
+function teamGcRecordDetail(heartbeat: WorkerHeartbeatFile | null, lifecycle: GjcTeamWorkerLifecycle | null): string {
+	return [
+		`heartbeat=${heartbeat ? "present" : "missing"}`,
+		...(heartbeat ? [`heartbeat_alive=${heartbeat.alive}`, `last_turn_at=${heartbeat.last_turn_at}`] : []),
+		`lifecycle=${lifecycle?.lifecycle_state ?? "missing"}`,
+		...(lifecycle?.pane_id ? [`pane_id=${lifecycle.pane_id}`] : []),
+		...(lifecycle?.stop_reason ? [`stop_reason=${lifecycle.stop_reason}`] : []),
+	].join(" ");
+}
+
+/** @internal */
+export async function listTeamWorkerGcRecords(teamRoot: string, probe: GcPidProbe): Promise<GcRecord[]> {
+	const teamEntries = await fs.readdir(teamRoot, { withFileTypes: true });
+	const records: GcRecord[] = [];
+	for (const teamEntry of teamEntries) {
+		if (!teamEntry.isDirectory()) continue;
+		const teamName = teamEntry.name;
+		const teamDirPath = path.join(teamRoot, teamName);
+		let workerEntries: import("node:fs").Dirent[];
+		try {
+			workerEntries = await fs.readdir(path.join(teamDirPath, "workers"), { withFileTypes: true });
+		} catch (error) {
+			if (isEnoent(error)) continue;
+			throw error;
+		}
+
+		for (const workerEntry of workerEntries) {
+			if (!workerEntry.isDirectory()) continue;
+			const workerId = workerEntry.name;
+			const dir = path.join(teamDirPath, "workers", workerId);
+			let heartbeat: WorkerHeartbeatFile | null = null;
+			let lifecycle: GjcTeamWorkerLifecycle | null = null;
+			try {
+				heartbeat = await readJsonFile<WorkerHeartbeatFile>(path.join(dir, "heartbeat.json"));
+				lifecycle = await readJsonFile<GjcTeamWorkerLifecycle>(path.join(dir, "lifecycle.json"));
+			} catch (error) {
+				records.push({
+					store: "team_workers",
+					id: `${teamName}/${workerId}`,
+					root: teamRoot,
+					path: dir,
+					pid_status: "none",
+					status: "malformed",
+					stale: false,
+					removable: false,
+					action: "none",
+					reason: "worker_state_malformed_kept",
+					error: error instanceof Error ? error.message : String(error),
+				});
+				continue;
+			}
+			const pids = collectTeamGcWorkerPids(heartbeat, lifecycle);
+			const { removable, pidStatus, pid } = classifyTeamGcWorkerPids(pids, probe);
+			const terminalLifecycle = lifecycle?.lifecycle_state === "failed" || lifecycle?.lifecycle_state === "stopped";
+			const status = removable
+				? "dead"
+				: pidStatus === "none" && terminalLifecycle
+					? "terminal_lifecycle"
+					: pidStatus === "none"
+						? "no_pid"
+						: pidStatus;
+			records.push({
+				store: "team_workers",
+				id: `${teamName}/${workerId}`,
+				root: teamRoot,
+				path: dir,
+				pid,
+				pid_status: pidStatus,
+				status,
+				stale: removable,
+				removable,
+				action: "none",
+				reason: removable
+					? "worker_all_pids_dead"
+					: pidStatus === "none" && terminalLifecycle
+						? "terminal_lifecycle_without_pid_kept"
+						: pidStatus === "none"
+							? "worker_pid_missing_kept"
+							: `worker_pid_${pidStatus}_kept`,
+				detail: teamGcRecordDetail(heartbeat, lifecycle),
+			});
+		}
+	}
+	return records;
+}
+
+/** @internal */
+export async function pruneTeamWorkerGcRecord(record: GcRecord, probe: GcPidProbe): Promise<boolean> {
+	if (!record.path || !record.id.includes("/")) return false;
+	const [teamName, workerId] = record.id.split("/", 2);
+	if (!teamName || !workerId) return false;
+	const teamDirPath = path.dirname(path.dirname(record.path));
+	const heartbeat = await readJsonFile<WorkerHeartbeatFile>(path.join(record.path, "heartbeat.json"));
+	const lifecycle = await readJsonFile<GjcTeamWorkerLifecycle>(path.join(record.path, "lifecycle.json"));
+	const pids = collectTeamGcWorkerPids(heartbeat, lifecycle);
+	if (!classifyTeamGcWorkerPids(pids, probe).removable) return false;
+
+	const claimDir = path.join(teamDirPath, "claims");
+	try {
+		for (const entry of await fs.readdir(claimDir, { withFileTypes: true })) {
+			if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+			const claimPath = path.join(claimDir, entry.name);
+			const claim = readClaimRecord(await readJsonFile<unknown>(claimPath));
+			if (claim?.owner !== workerId) continue;
+			await removeFileAudited(claimPath, stateWriterOptions(claimPath, "prune", "gc-team-worker"));
+		}
+	} catch (error) {
+		if (!isEnoent(error)) throw error;
+	}
+
+	for (const task of await readTasks(teamDirPath)) {
+		if (task.claim?.owner !== workerId && task.assignee !== workerId) continue;
+		if (task.status === "completed" || task.status === "failed") continue;
+		await writeTask(teamDirPath, {
+			...task,
+			status: "pending",
+			assignee: undefined,
+			claim: undefined,
+			version: task.version + 1,
+			updated_at: now(),
+		});
+	}
+
+	// Remove the stale worker record dir itself so a removable record always
+	// results in an observable removal, even when it owns no claims/tasks.
+	await fs.rm(record.path, { recursive: true, force: true });
+	return true;
+}
 function stateCategoryForJsonPath(filePath: string): "state" | "ledger" {
 	return filePath.endsWith(".jsonl") || filePath.includes(`${path.sep}telemetry${path.sep}`) ? "ledger" : "state";
 }
@@ -1633,7 +1803,7 @@ function buildTeamTmuxLeaderRequirementMessage(detail?: string): string {
 }
 function readGjcTmuxProfileValue(tmuxCommand: string, sessionName: string): string {
 	const result = Bun.spawnSync(
-		[tmuxCommand, "show-options", "-qv", "-t", `=${sessionName}`, GJC_TMUX_PROFILE_OPTION],
+		[tmuxCommand, "show-options", "-qv", "-t", buildGjcTmuxExactOptionTarget(sessionName), GJC_TMUX_PROFILE_OPTION],
 		{
 			stdout: "pipe",
 			stderr: "pipe",
@@ -1645,7 +1815,14 @@ function readGjcTmuxProfileValue(tmuxCommand: string, sessionName: string): stri
 
 function retagGjcLaunchedTmuxSession(tmuxCommand: string, sessionName: string): boolean {
 	const result = Bun.spawnSync(
-		[tmuxCommand, "set-option", "-t", `=${sessionName}`, GJC_TMUX_PROFILE_OPTION, GJC_TMUX_PROFILE_VALUE],
+		[
+			tmuxCommand,
+			"set-option",
+			"-t",
+			buildGjcTmuxExactOptionTarget(sessionName),
+			GJC_TMUX_PROFILE_OPTION,
+			GJC_TMUX_PROFILE_VALUE,
+		],
 		{
 			stdout: "pipe",
 			stderr: "pipe",

package/src/gjc-runtime/tmux-common.ts

@@ -32,6 +32,20 @@ export function resolveGjcTmuxCommand(env: NodeJS.ProcessEnv = process.env): str
 	return env[GJC_TMUX_COMMAND_ENV]?.trim() || env.GJC_TEAM_TMUX_COMMAND?.trim() || "tmux";
 }
 
+/**
+ * Build the exact-session target for tmux *option* commands
+ * (`show-options` / `set-option`) and `display-message -t`.
+ *
+ * Session-scoped commands such as `kill-session` / `attach-session` resolve a
+ * bare exact target (`=NAME`), but tmux 3.6a refuses to resolve a bare `=NAME`
+ * for option/display commands. Appending the empty window separator (`=NAME:`)
+ * keeps the exact-session match while giving tmux the window-qualified target
+ * those commands require. See gajae-code#580.
+ */
+export function buildGjcTmuxExactOptionTarget(sessionName: string): string {
+	return `=${sessionName}:`;
+}
+
 export const GJC_TMUX_UNTAGGED_REASON = "gjc_tmux_session_untagged";
 
 export function buildGjcTmuxUntaggedSessionHint(tmuxCommand: string): string {