@gajae-code/coding-agent 0.2.5 → 0.3.1

package/dist/types/gjc-runtime/state-schema.d.ts

@@ -0,0 +1,317 @@
+import { z } from "zod";
+export declare const WorkflowStateContentChecksumSchema: z.ZodObject<{
+    algorithm: z.ZodLiteral<"sha256">;
+    value: z.ZodString;
+    covered_path: z.ZodString;
+    computed_at: z.ZodString;
+}, z.core.$loose>;
+/** Lenient receipt schema for reads (mirrors WorkflowStateReceipt). */
+export declare const WorkflowStateReceiptSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    skill: z.ZodEnum<{
+        "deep-interview": "deep-interview";
+        ralplan: "ralplan";
+        team: "team";
+        ultragoal: "ultragoal";
+    }>;
+    owner: z.ZodEnum<{
+        "gjc-hook": "gjc-hook";
+        "gjc-runtime": "gjc-runtime";
+        "gjc-state-cli": "gjc-state-cli";
+    }>;
+    command: z.ZodString;
+    state_path: z.ZodString;
+    storage_path: z.ZodString;
+    mutated_at: z.ZodString;
+    fresh_until: z.ZodString;
+    status: z.ZodEnum<{
+        fresh: "fresh";
+        stale: "stale";
+    }>;
+    mutation_id: z.ZodString;
+    verb: z.ZodOptional<z.ZodString>;
+    from_phase: z.ZodOptional<z.ZodString>;
+    to_phase: z.ZodOptional<z.ZodString>;
+    forced: z.ZodOptional<z.ZodBoolean>;
+    paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    content_sha256: z.ZodOptional<z.ZodObject<{
+        algorithm: z.ZodLiteral<"sha256">;
+        value: z.ZodString;
+        covered_path: z.ZodString;
+        computed_at: z.ZodString;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+/** Lenient envelope schema for reads. Every non-structural field optional. */
+export declare const WorkflowStateEnvelopeSchema: z.ZodObject<{
+    skill: z.ZodOptional<z.ZodString>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    current_phase: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodNumber>;
+    updated_at: z.ZodOptional<z.ZodString>;
+    session_id: z.ZodOptional<z.ZodString>;
+    receipt: z.ZodOptional<z.ZodObject<{
+        version: z.ZodNumber;
+        skill: z.ZodEnum<{
+            "deep-interview": "deep-interview";
+            ralplan: "ralplan";
+            team: "team";
+            ultragoal: "ultragoal";
+        }>;
+        owner: z.ZodEnum<{
+            "gjc-hook": "gjc-hook";
+            "gjc-runtime": "gjc-runtime";
+            "gjc-state-cli": "gjc-state-cli";
+        }>;
+        command: z.ZodString;
+        state_path: z.ZodString;
+        storage_path: z.ZodString;
+        mutated_at: z.ZodString;
+        fresh_until: z.ZodString;
+        status: z.ZodEnum<{
+            fresh: "fresh";
+            stale: "stale";
+        }>;
+        mutation_id: z.ZodString;
+        verb: z.ZodOptional<z.ZodString>;
+        from_phase: z.ZodOptional<z.ZodString>;
+        to_phase: z.ZodOptional<z.ZodString>;
+        forced: z.ZodOptional<z.ZodBoolean>;
+        paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        content_sha256: z.ZodOptional<z.ZodObject<{
+            algorithm: z.ZodLiteral<"sha256">;
+            value: z.ZodString;
+            covered_path: z.ZodString;
+            computed_at: z.ZodString;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+/**
+ * Strict receipt required on WRITE (post checksum-stamping). Anchored to the
+ * fields the sanctioned writer emits — `content_sha256` is REQUIRED here.
+ */
+export declare const RequiredWorkflowStateReceiptSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    skill: z.ZodEnum<{
+        "deep-interview": "deep-interview";
+        ralplan: "ralplan";
+        team: "team";
+        ultragoal: "ultragoal";
+    }>;
+    owner: z.ZodEnum<{
+        "gjc-hook": "gjc-hook";
+        "gjc-runtime": "gjc-runtime";
+        "gjc-state-cli": "gjc-state-cli";
+    }>;
+    command: z.ZodString;
+    state_path: z.ZodString;
+    storage_path: z.ZodString;
+    mutated_at: z.ZodString;
+    fresh_until: z.ZodString;
+    status: z.ZodEnum<{
+        fresh: "fresh";
+        stale: "stale";
+    }>;
+    mutation_id: z.ZodString;
+    content_sha256: z.ZodObject<{
+        algorithm: z.ZodLiteral<"sha256">;
+        value: z.ZodString;
+        covered_path: z.ZodString;
+        computed_at: z.ZodString;
+    }, z.core.$loose>;
+}, z.core.$loose>;
+/**
+ * Write-side fail-closed gate: the serialized on-disk envelope must satisfy
+ * this after checksum stamping. Anchored to current sanctioned-writer output.
+ */
+export declare const RequiredOnWriteEnvelopeSchema: z.ZodObject<{
+    skill: z.ZodEnum<{
+        "deep-interview": "deep-interview";
+        ralplan: "ralplan";
+        team: "team";
+        ultragoal: "ultragoal";
+    }>;
+    version: z.ZodLiteral<2>;
+    updated_at: z.ZodString;
+    current_phase: z.ZodString;
+    active: z.ZodBoolean;
+    receipt: z.ZodObject<{
+        version: z.ZodNumber;
+        skill: z.ZodEnum<{
+            "deep-interview": "deep-interview";
+            ralplan: "ralplan";
+            team: "team";
+            ultragoal: "ultragoal";
+        }>;
+        owner: z.ZodEnum<{
+            "gjc-hook": "gjc-hook";
+            "gjc-runtime": "gjc-runtime";
+            "gjc-state-cli": "gjc-state-cli";
+        }>;
+        command: z.ZodString;
+        state_path: z.ZodString;
+        storage_path: z.ZodString;
+        mutated_at: z.ZodString;
+        fresh_until: z.ZodString;
+        status: z.ZodEnum<{
+            fresh: "fresh";
+            stale: "stale";
+        }>;
+        mutation_id: z.ZodString;
+        content_sha256: z.ZodObject<{
+            algorithm: z.ZodLiteral<"sha256">;
+            value: z.ZodString;
+            covered_path: z.ZodString;
+            computed_at: z.ZodString;
+        }, z.core.$loose>;
+    }, z.core.$loose>;
+}, z.core.$loose>;
+/** Per-skill mode state consumed by hooks / the mutation guard. */
+export declare const ModeStateSchema: z.ZodObject<{
+    active: z.ZodOptional<z.ZodBoolean>;
+    current_phase: z.ZodOptional<z.ZodString>;
+    skill: z.ZodOptional<z.ZodString>;
+    session_id: z.ZodOptional<z.ZodString>;
+    thread_id: z.ZodOptional<z.ZodString>;
+    cwd: z.ZodOptional<z.ZodString>;
+    updated_at: z.ZodOptional<z.ZodString>;
+    handoff_from: z.ZodOptional<z.ZodString>;
+    handoff_to: z.ZodOptional<z.ZodString>;
+    handoff_at: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export declare const SkillActiveEntrySchema: z.ZodObject<{
+    skill: z.ZodString;
+    phase: z.ZodOptional<z.ZodString>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    activated_at: z.ZodOptional<z.ZodString>;
+    updated_at: z.ZodOptional<z.ZodString>;
+    session_id: z.ZodOptional<z.ZodString>;
+    thread_id: z.ZodOptional<z.ZodString>;
+    turn_id: z.ZodOptional<z.ZodString>;
+    stale: z.ZodOptional<z.ZodBoolean>;
+    handoff_from: z.ZodOptional<z.ZodString>;
+    handoff_to: z.ZodOptional<z.ZodString>;
+    handoff_at: z.ZodOptional<z.ZodString>;
+    receipt: z.ZodOptional<z.ZodObject<{
+        version: z.ZodNumber;
+        skill: z.ZodEnum<{
+            "deep-interview": "deep-interview";
+            ralplan: "ralplan";
+            team: "team";
+            ultragoal: "ultragoal";
+        }>;
+        owner: z.ZodEnum<{
+            "gjc-hook": "gjc-hook";
+            "gjc-runtime": "gjc-runtime";
+            "gjc-state-cli": "gjc-state-cli";
+        }>;
+        command: z.ZodString;
+        state_path: z.ZodString;
+        storage_path: z.ZodString;
+        mutated_at: z.ZodString;
+        fresh_until: z.ZodString;
+        status: z.ZodEnum<{
+            fresh: "fresh";
+            stale: "stale";
+        }>;
+        mutation_id: z.ZodString;
+        verb: z.ZodOptional<z.ZodString>;
+        from_phase: z.ZodOptional<z.ZodString>;
+        to_phase: z.ZodOptional<z.ZodString>;
+        forced: z.ZodOptional<z.ZodBoolean>;
+        paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        content_sha256: z.ZodOptional<z.ZodObject<{
+            algorithm: z.ZodLiteral<"sha256">;
+            value: z.ZodString;
+            covered_path: z.ZodString;
+            computed_at: z.ZodString;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export declare const SkillActiveStateSchema: z.ZodObject<{
+    version: z.ZodOptional<z.ZodNumber>;
+    active: z.ZodOptional<z.ZodBoolean>;
+    skill: z.ZodOptional<z.ZodString>;
+    keyword: z.ZodOptional<z.ZodString>;
+    phase: z.ZodOptional<z.ZodString>;
+    activated_at: z.ZodOptional<z.ZodString>;
+    updated_at: z.ZodOptional<z.ZodString>;
+    source: z.ZodOptional<z.ZodString>;
+    session_id: z.ZodOptional<z.ZodString>;
+    thread_id: z.ZodOptional<z.ZodString>;
+    turn_id: z.ZodOptional<z.ZodString>;
+    active_skills: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        skill: z.ZodString;
+        phase: z.ZodOptional<z.ZodString>;
+        active: z.ZodOptional<z.ZodBoolean>;
+        activated_at: z.ZodOptional<z.ZodString>;
+        updated_at: z.ZodOptional<z.ZodString>;
+        session_id: z.ZodOptional<z.ZodString>;
+        thread_id: z.ZodOptional<z.ZodString>;
+        turn_id: z.ZodOptional<z.ZodString>;
+        stale: z.ZodOptional<z.ZodBoolean>;
+        handoff_from: z.ZodOptional<z.ZodString>;
+        handoff_to: z.ZodOptional<z.ZodString>;
+        handoff_at: z.ZodOptional<z.ZodString>;
+        receipt: z.ZodOptional<z.ZodObject<{
+            version: z.ZodNumber;
+            skill: z.ZodEnum<{
+                "deep-interview": "deep-interview";
+                ralplan: "ralplan";
+                team: "team";
+                ultragoal: "ultragoal";
+            }>;
+            owner: z.ZodEnum<{
+                "gjc-hook": "gjc-hook";
+                "gjc-runtime": "gjc-runtime";
+                "gjc-state-cli": "gjc-state-cli";
+            }>;
+            command: z.ZodString;
+            state_path: z.ZodString;
+            storage_path: z.ZodString;
+            mutated_at: z.ZodString;
+            fresh_until: z.ZodString;
+            status: z.ZodEnum<{
+                fresh: "fresh";
+                stale: "stale";
+            }>;
+            mutation_id: z.ZodString;
+            verb: z.ZodOptional<z.ZodString>;
+            from_phase: z.ZodOptional<z.ZodString>;
+            to_phase: z.ZodOptional<z.ZodString>;
+            forced: z.ZodOptional<z.ZodBoolean>;
+            paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            content_sha256: z.ZodOptional<z.ZodObject<{
+                algorithm: z.ZodLiteral<"sha256">;
+                value: z.ZodString;
+                covered_path: z.ZodString;
+                computed_at: z.ZodString;
+            }, z.core.$loose>>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>>;
+}, z.core.$loose>;
+export type WorkflowStateEnvelope = z.infer<typeof WorkflowStateEnvelopeSchema>;
+export type RequiredOnWriteEnvelope = z.infer<typeof RequiredOnWriteEnvelopeSchema>;
+export type ModeStateParsed = z.infer<typeof ModeStateSchema>;
+export type SkillActiveStateParsed = z.infer<typeof SkillActiveStateSchema>;
+/**
+ * Validated read result.
+ * - `null`        → file absent (ENOENT); callers treat as no state.
+ * - `{ok:true}`   → parsed + schema-valid.
+ * - `{ok:false}`  → present but unparseable or schema-invalid. Callers fail
+ *                   OPEN (normalize/log), never crash — preserving v2 reads.
+ */
+export type ReadGjcJsonResult<T> = {
+    ok: true;
+    value: T;
+    raw: unknown;
+} | {
+    ok: false;
+    error: string;
+    raw: unknown;
+};
+/**
+ * Parse + schema-validate a `.gjc` JSON file at the read boundary.
+ * Returns `null` when the file is absent. Fail-open: an invalid file yields
+ * `{ ok: false }` with the raw value attached so the caller can normalize/log.
+ */
+export declare function readGjcJson<T>(filePath: string, schema: z.ZodType<T>): Promise<ReadGjcJsonResult<T> | null>;

package/dist/types/gjc-runtime/state-validation.d.ts

@@ -0,0 +1,6 @@
+import type { CanonicalGjcWorkflowSkill } from "../skill-state/active-state";
+export interface StateValidationResult {
+    valid: boolean;
+    error?: string;
+}
+export declare function validateWorkflowStateEnvelope(skill: CanonicalGjcWorkflowSkill, state: unknown): StateValidationResult;

package/dist/types/gjc-runtime/state-writer.d.ts

@@ -0,0 +1,147 @@
+import * as fs from "node:fs/promises";
+import type { SkillActiveEntry } from "../skill-state/active-state";
+import { type AuditEntry, type CanonicalGjcWorkflowSkill, type WorkflowStateMutationOwner } from "../skill-state/workflow-state-contract";
+/**
+ * Sole sanctioned project `.gjc/**` writer module (gate G1).
+ *
+ * All native `.gjc/**` filesystem mutations must route through these primitives.
+ * The primitives validate project `.gjc/**` ownership, create parent directories,
+ * and emit workflow receipts or audit entries where applicable by the caller's
+ * supplied mutation context. No lockfiles are used; isolation is by atomic rename,
+ * append, O_EXCL creates, conditional deletes, per-entry active-state files,
+ * and derived active-state snapshots.
+ * Transaction journals are per mutation id under `.gjc/state/transactions/`;
+ * they are recovery evidence only, never global locks or waiters, so stale
+ * journals do not block unrelated state reads or writes.
+ */
+export type WriterCategory = "state" | "artifact" | "ledger" | "log" | "report" | "agents" | "prune" | "force" | "transaction";
+export interface StateWriterReceiptContext {
+    cwd?: string;
+    skill: CanonicalGjcWorkflowSkill;
+    owner: WorkflowStateMutationOwner;
+    command: string;
+    sessionId?: string;
+    mutationId?: string;
+    nowIso?: string;
+}
+export interface StateWriterAuditContext {
+    cwd?: string;
+    category: WriterCategory;
+    verb: string;
+    owner: WorkflowStateMutationOwner;
+    skill?: CanonicalGjcWorkflowSkill | string;
+    mutationId?: string;
+    fromPhase?: string;
+    toPhase?: string;
+    forced?: boolean;
+}
+export interface WorkflowEnvelopeIntegrityMismatch {
+    path: string;
+    expected: string;
+    actual: string;
+}
+export interface WorkflowTransactionJournal {
+    version: 1;
+    mutation_id: string;
+    status: "pending" | "committed";
+    created_at: string;
+    updated_at: string;
+    caller?: CanonicalGjcWorkflowSkill;
+    callee?: CanonicalGjcWorkflowSkill;
+    paths: string[];
+    steps: string[];
+}
+export interface StateWriterOptions {
+    cwd?: string;
+    receipt?: StateWriterReceiptContext;
+    audit?: StateWriterAuditContext;
+}
+export interface DeleteIfOwnedOptions extends StateWriterOptions {
+    predicate?: (current: unknown) => boolean | Promise<boolean>;
+}
+export interface DeleteResult {
+    path: string;
+    deleted: boolean;
+}
+export interface ActiveSessionScope {
+    sessionId?: string;
+}
+export interface ActiveEntryWriteResult {
+    entryPath: string;
+    snapshotPath: string;
+}
+export interface HardPruneSelectorContext {
+    path: string;
+    value: unknown;
+}
+export interface GenericHardPruneTarget {
+    path: string;
+    category: WriterCategory | string;
+}
+export interface GenericHardPruneSelectorContext {
+    path: string;
+    category: WriterCategory | string;
+    stat: Awaited<ReturnType<typeof fs.stat>>;
+    readJson: () => Promise<unknown>;
+}
+export type GenericHardPruneSelector = (context: GenericHardPruneSelectorContext) => boolean | Promise<boolean>;
+export interface ForceOverwriteOptions extends StateWriterOptions {
+    raw?: boolean;
+}
+export type HardPruneSelector = (context: HardPruneSelectorContext) => boolean | Promise<boolean>;
+export declare class AlreadyExistsError extends Error {
+    readonly path: string;
+    constructor(path: string);
+}
+export type StrictMutationReadResult = {
+    kind: "absent";
+} | {
+    kind: "corrupt";
+    error: string;
+} | {
+    kind: "valid";
+    value: Record<string, unknown>;
+};
+export declare function readExistingStateForMutation(filePath: string): Promise<StrictMutationReadResult>;
+export declare function workflowEnvelopeContentSha256(value: unknown): string;
+export declare function stampWorkflowEnvelopeChecksum<T>(value: T, filePath: string, computedAt?: string): T;
+export declare function detectWorkflowEnvelopeIntegrityMismatch(filePath: string): Promise<WorkflowEnvelopeIntegrityMismatch | undefined>;
+export declare function writeJsonAtomic(targetPath: string, value: unknown, options?: StateWriterOptions): Promise<string>;
+export declare function writeWorkflowEnvelopeAtomic(targetPath: string, value: unknown, options?: StateWriterOptions): Promise<string>;
+export declare function writeTextAtomic(targetPath: string, text: string, options?: StateWriterOptions): Promise<string>;
+export declare function updateJsonAtomic<T = unknown>(targetPath: string, mutator: (current: T | undefined) => T | Promise<T>, options?: StateWriterOptions): Promise<string>;
+export declare function appendJsonl(targetPath: string, entry: unknown, options?: StateWriterOptions): Promise<string>;
+export declare function appendText(targetPath: string, text: string, options?: StateWriterOptions): Promise<string>;
+export declare function createJsonNoClobber(targetPath: string, value: unknown, options?: StateWriterOptions): Promise<string>;
+export declare function deleteIfOwned(targetPath: string, predicateOrOptions?: ((current: unknown) => boolean | Promise<boolean>) | DeleteIfOwnedOptions): Promise<DeleteResult>;
+export declare function removeFileAudited(targetPath: string, options?: StateWriterOptions): Promise<DeleteResult>;
+/**
+ * Active entry files under `.gjc/state/active/<skill>.json` and
+ * `.gjc/state/sessions/<id>/active/<skill>.json` are authoritative. The
+ * adjacent `skill-active-state.json` file is only a derived cache rebuilt from
+ * those entries, so concurrent snapshot rebuilds can race without losing any
+ * writer's per-skill state.
+ */
+export declare function writeActiveEntry(cwd: string, sessionScope: string | ActiveSessionScope | undefined, skill: string, entry: SkillActiveEntry, options?: StateWriterOptions): Promise<string>;
+export declare function removeActiveEntry(cwd: string, sessionScope: string | ActiveSessionScope | undefined, skill: string, options?: StateWriterOptions): Promise<DeleteResult>;
+export declare function readActiveEntries(cwd: string, sessionScope?: string | ActiveSessionScope): Promise<SkillActiveEntry[]>;
+export declare function rebuildActiveSnapshot(cwd: string, sessionScope?: string | ActiveSessionScope, options?: StateWriterOptions): Promise<string>;
+export declare function mergeActiveState(cwd: string, sessionScope: string | ActiveSessionScope | undefined, skill: string, entry: SkillActiveEntry, options?: StateWriterOptions): Promise<ActiveEntryWriteResult>;
+export declare function writeArtifact(targetPath: string, content: string, options?: StateWriterOptions): Promise<string>;
+export declare function writeReport(targetPath: string, content: string, options?: StateWriterOptions): Promise<string>;
+export declare function writeLogJsonl(targetPath: string, entry: unknown, options?: StateWriterOptions): Promise<string>;
+export declare function softDelete(targetPath: string, meta: Record<string, unknown>, options?: StateWriterOptions): Promise<string>;
+export declare function hardPruneJson(targetPaths: readonly string[], selector: HardPruneSelector, options?: StateWriterOptions): Promise<string[]>;
+export declare function hardPrune(targets: readonly GenericHardPruneTarget[], selector: GenericHardPruneSelector, options?: StateWriterOptions): Promise<string[]>;
+export declare function forceOverwrite(targetPath: string, rawValue: unknown, options?: ForceOverwriteOptions): Promise<string>;
+export declare function appendAuditEntry(cwd: string, entry: AuditEntry): Promise<string>;
+export declare function readWorkflowTransactionJournal(cwd: string, mutationId: string): Promise<WorkflowTransactionJournal | undefined>;
+export declare function beginWorkflowTransactionJournal(input: {
+    cwd: string;
+    mutationId: string;
+    caller?: CanonicalGjcWorkflowSkill;
+    callee?: CanonicalGjcWorkflowSkill;
+    paths: string[];
+}): Promise<string>;
+export declare function updateWorkflowTransactionJournal(cwd: string, mutationId: string, patch: Partial<WorkflowTransactionJournal>): Promise<string>;
+export declare function completeWorkflowTransactionJournal(cwd: string, mutationId: string): Promise<void>;

package/dist/types/gjc-runtime/team-runtime.d.ts

@@ -2,6 +2,8 @@ import type { WorkflowHudSummary } from "../skill-state/active-state";
 export type GjcTeamPhase = "starting" | "running" | "awaiting_integration" | "complete" | "failed" | "cancelled";
 export type GjcTeamTaskStatus = "pending" | "blocked" | "in_progress" | "completed" | "failed";
 export type GjcWorkerStatusState = "idle" | "working" | "blocked" | "done" | "failed" | "draining" | "unknown";
+export type GjcTeamWorkerLifecycleState = "starting" | "ready" | "working" | "draining" | "stopped" | "failed" | "unknown";
+export type GjcTeamShutdownMode = "graceful" | "force" | "abort";
 export declare const GJC_TEAM_DEFAULT_WORKERS = 3;
 export declare const GJC_TEAM_MAX_WORKERS = 20;
 export type GjcTeamWorkerCli = "gjc";
@@ -33,6 +35,25 @@ export interface GjcTeamTaskClaim {
     token: string;
     leased_until: string;
 }
+export type GjcTeamTaskCompletionEvidenceKind = "command" | "inspection" | "artifact";
+export type GjcTeamTaskCompletionEvidenceStatus = "passed" | "failed" | "not_run" | "verified" | "rejected";
+export interface GjcTeamTaskCompletionEvidenceItem {
+    kind: GjcTeamTaskCompletionEvidenceKind;
+    status: GjcTeamTaskCompletionEvidenceStatus;
+    summary: string;
+    command?: string;
+    artifact?: string;
+    location?: string;
+    output?: string;
+}
+export interface GjcTeamTaskCompletionEvidence {
+    summary: string;
+    items: GjcTeamTaskCompletionEvidenceItem[];
+    files?: string[];
+    notes?: string;
+    recorded_by: string;
+    recorded_at: string;
+}
 export interface GjcTeamTask {
     id: string;
     subject: string;
@@ -43,9 +64,13 @@ export interface GjcTeamTask {
     assignee?: string;
     owner?: string;
     result?: string;
+    completion_evidence?: GjcTeamTaskCompletionEvidence;
     error?: string;
     blocked_by?: string[];
     depends_on?: string[];
+    lane?: string;
+    required_role?: string;
+    allowed_roles?: string[];
     version: number;
     claim?: GjcTeamTaskClaim;
     created_at: string;
@@ -102,6 +127,22 @@ export interface GjcTeamMonitorSnapshot {
     integration_by_worker: Record<string, GjcTeamWorkerIntegrationState>;
     updated_at: string;
 }
+export interface GjcTeamWorkerLifecycle {
+    worker: string;
+    lifecycle_state: GjcTeamWorkerLifecycleState;
+    worker_status_state: GjcWorkerStatusState;
+    pane_id?: string;
+    pid?: number;
+    started_at?: string;
+    updated_at: string;
+    stopped_at?: string;
+    stop_reason?: string;
+    shutdown_request_id?: string;
+    shutdown_requested_at?: string;
+    shutdown_acknowledged_at?: string;
+    shutdown_ack_status?: string;
+    shutdown_mode?: GjcTeamShutdownMode;
+}
 export type GjcTeamNotificationDeliveryState = "pending" | "sent" | "queued" | "deferred" | "failed" | "delivered" | "acknowledged";
 export type GjcTeamPaneAttemptResult = "sent" | "queued" | "deferred" | "failed";
 export interface GjcTeamNotification {
@@ -139,9 +180,13 @@ export interface GjcTeamSnapshot {
     task_counts: Record<GjcTeamTaskStatus, number>;
     workers: GjcTeamWorker[];
     integration_by_worker?: Record<string, GjcTeamWorkerIntegrationState>;
+    worker_lifecycle_by_id: Record<string, GjcTeamWorkerLifecycle>;
     notification_summary: GjcTeamNotificationSummary;
     updated_at: string;
 }
+export interface GjcTeamSnapshotOptions {
+    reconcileNotifications?: boolean;
+}
 export interface GjcTeamStartOptions {
     workerCount: number;
     agentType: string;
@@ -159,6 +204,16 @@ export interface GjcTeamApiClaimResult {
     claim_token?: string;
     reason?: string;
 }
+export type GjcTeamLivenessRecoveryReason = "claim_expired" | "stale_heartbeat" | "missing_pane" | "worker_lifecycle_failed" | "worker_lifecycle_stopped";
+export interface GjcTeamRecoveredClaim {
+    task_id: string;
+    worker: string;
+    reasons: GjcTeamLivenessRecoveryReason[];
+}
+export interface GjcTeamLivenessRecoveryResult {
+    recovered_claims: GjcTeamRecoveredClaim[];
+    stale_workers: Record<string, GjcTeamLivenessRecoveryReason[]>;
+}
 export interface GjcTeamMailboxMessage {
     message_id: string;
     from_worker: string;
@@ -181,6 +236,19 @@ export interface GjcTeamEvent {
     message?: string;
     data?: Record<string, unknown>;
 }
+export interface GjcTeamTraceEvent {
+    schema_version: 1;
+    trace_id: string;
+    span_id: string;
+    source_event_id: string;
+    event_type: string;
+    ts: string;
+    worker?: string;
+    task_id?: string;
+    message?: string;
+    evidence_refs?: string[];
+    data?: Record<string, unknown>;
+}
 interface WorkerStatusFile {
     state: GjcWorkerStatusState;
     current_task_id?: string;
@@ -202,8 +270,11 @@ export interface GjcWorkerIntegrationAttemptRequestResult {
     head?: string | null;
     status?: GjcWorkerCheckpointClassification["kind"];
 }
-export declare const GJC_TEAM_API_OPERATIONS: readonly ["send-message", "broadcast", "mailbox-list", "mailbox-mark-delivered", "mailbox-mark-notified", "notification-list", "notification-read", "notification-replay", "notification-mark-pane-attempt", "worker-startup-ack", "create-task", "read-task", "list-tasks", "update-task", "claim-task", "transition-task-status", "transition-task", "release-task-claim", "read-config", "read-manifest", "read-worker-status", "read-worker-heartbeat", "update-worker-heartbeat", "write-worker-inbox", "write-worker-identity", "append-event", "read-events", "await-event", "write-shutdown-request", "read-shutdown-ack", "read-monitor-snapshot", "write-monitor-snapshot", "read-task-approval", "write-task-approval"];
+export declare const GJC_TEAM_API_OPERATIONS: readonly ["send-message", "broadcast", "mailbox-list", "mailbox-mark-delivered", "mailbox-mark-notified", "notification-list", "notification-read", "notification-replay", "notification-mark-pane-attempt", "worker-startup-ack", "create-task", "read-task", "list-tasks", "update-task", "claim-task", "transition-task-status", "transition-task", "release-task-claim", "read-config", "read-manifest", "read-worker-status", "update-worker-status", "read-worker-heartbeat", "recover-stale-claims", "update-worker-heartbeat", "write-worker-inbox", "write-worker-identity", "append-event", "read-events", "read-traces", "await-event", "write-shutdown-request", "read-shutdown-ack", "read-monitor-snapshot", "write-monitor-snapshot", "read-task-approval", "write-task-approval"];
 export declare function resolveGjcTeamStateRoot(cwd?: string, env?: NodeJS.ProcessEnv): string;
+export declare function persistGjcTeamModeStateSummary(snapshot: GjcTeamSnapshot, cwd?: string): Promise<void>;
+export declare function recoverGjcTeamStaleClaims(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamLivenessRecoveryResult>;
+type GjcTeamTaskMetadataInput = Partial<Pick<GjcTeamTask, "owner" | "lane" | "required_role" | "allowed_roles" | "depends_on" | "blocked_by">>;
 export declare function resolveGjcTmuxCommand(env?: NodeJS.ProcessEnv): string;
 export declare function resolveGjcWorkerCommand(cwd?: string, env?: NodeJS.ProcessEnv): string;
 export type GjcWorkerCheckpointClassification = {
@@ -229,7 +300,8 @@ export declare function classifyGjcTeamCheckpointFiles(files: string[]): {
 };
 export declare function classifyWorkerCheckpointStatus(cwd: string): GjcWorkerCheckpointClassification;
 export declare function startGjcTeam(options: GjcTeamStartOptions): Promise<GjcTeamSnapshot>;
-export declare function readGjcTeamSnapshot(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamSnapshot>;
+export declare function readGjcTeamSnapshot(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv, options?: GjcTeamSnapshotOptions): Promise<GjcTeamSnapshot>;
+export declare function monitorGjcTeamSnapshot(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamSnapshot>;
 export declare function requestGjcWorkerIntegrationAttempt(cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcWorkerIntegrationAttemptRequestResult>;
 export declare function buildTeamHudSummary(snapshot: GjcTeamSnapshot, latestEvent?: GjcTeamEvent, latestMessage?: GjcTeamMailboxMessage): Promise<WorkflowHudSummary>;
 export declare function monitorGjcTeam(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamSnapshot>;
@@ -237,11 +309,11 @@ export declare function listGjcTeams(cwd?: string, env?: NodeJS.ProcessEnv): Pro
 export declare function shutdownGjcTeam(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamSnapshot>;
 export declare function listGjcTeamTasks(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamTask[]>;
 export declare function readGjcTeamTask(teamName: string, taskId: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamTask>;
-export declare function createGjcTeamTask(teamName: string, subject: string, description: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamTask>;
-export declare function updateGjcTeamTask(teamName: string, taskId: string, updates: Partial<Pick<GjcTeamTask, "subject" | "description" | "blocked_by" | "depends_on">>, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamTask>;
+export declare function createGjcTeamTask(teamName: string, subject: string, description: string, cwd?: string, env?: NodeJS.ProcessEnv, taskOptions?: GjcTeamTaskMetadataInput): Promise<GjcTeamTask>;
+export declare function updateGjcTeamTask(teamName: string, taskId: string, updates: Partial<Pick<GjcTeamTask, "subject" | "description" | "blocked_by" | "depends_on" | "lane" | "required_role" | "allowed_roles">>, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamTask>;
 export declare function claimGjcTeamTask(teamName: string, workerId: string, cwd?: string, env?: NodeJS.ProcessEnv, taskId?: string): Promise<GjcTeamApiClaimResult>;
-export declare function transitionGjcTeamTaskStatus(teamName: string, taskId: string, status: GjcTeamTaskStatus, cwd?: string, env?: NodeJS.ProcessEnv, claimToken?: string, workerId?: string, evidence?: string): Promise<GjcTeamTask>;
-export declare function transitionGjcTeamTask(teamName: string, taskId: string, status: GjcTeamTaskStatus | "complete", cwd?: string, env?: NodeJS.ProcessEnv, claimToken?: string): Promise<GjcTeamTask>;
+export declare function transitionGjcTeamTaskStatus(teamName: string, taskId: string, status: GjcTeamTaskStatus, cwd?: string, env?: NodeJS.ProcessEnv, claimToken?: string, workerId?: string, completionEvidenceInput?: unknown): Promise<GjcTeamTask>;
+export declare function transitionGjcTeamTask(teamName: string, taskId: string, status: GjcTeamTaskStatus | "complete", cwd?: string, env?: NodeJS.ProcessEnv, claimToken?: string, completionEvidenceInput?: unknown): Promise<GjcTeamTask>;
 export declare function releaseGjcTeamTaskClaim(teamName: string, taskId: string, claimToken: string, workerId: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamTask>;
 export declare function replayGjcTeamNotifications(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<{
     notifications: GjcTeamNotification[];
@@ -252,6 +324,7 @@ export declare function broadcastGjcTeamMessage(teamName: string, fromWorker: st
 export declare function listGjcTeamMailbox(teamName: string, worker: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamMailboxMessage[]>;
 export declare function markGjcTeamMailboxMessage(teamName: string, worker: string, messageId: string, field: "delivered_at" | "notified_at", cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamMailboxMessage>;
 export declare function readGjcWorkerStatus(teamName: string, worker: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<WorkerStatusFile>;
+export declare function updateGjcWorkerStatus(teamName: string, worker: string, status: GjcWorkerStatusState, cwd?: string, env?: NodeJS.ProcessEnv, currentTaskId?: string, reason?: string): Promise<WorkerStatusFile>;
 export declare function readGjcWorkerHeartbeat(teamName: string, worker: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<WorkerHeartbeatFile | null>;
 export declare function updateGjcWorkerHeartbeat(teamName: string, worker: string, heartbeat: WorkerHeartbeatFile, cwd?: string, env?: NodeJS.ProcessEnv): Promise<WorkerHeartbeatFile>;
 export declare function writeGjcWorkerInbox(teamName: string, worker: string, content: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<{
@@ -259,6 +332,7 @@ export declare function writeGjcWorkerInbox(teamName: string, worker: string, co
 }>;
 export declare function writeGjcWorkerIdentity(teamName: string, worker: GjcTeamWorker, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamWorker>;
 export declare function readGjcTeamEvents(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamEvent[]>;
+export declare function readGjcTeamTraces(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamTraceEvent[]>;
 export declare function appendGjcTeamEvent(teamName: string, type: string, worker?: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<GjcTeamEvent>;
 export declare function awaitGjcTeamEvent(teamName: string, _timeoutMs?: number, cwd?: string, env?: NodeJS.ProcessEnv): Promise<{
     status: "event" | "timeout";
@@ -268,7 +342,7 @@ export declare function writeGjcMonitorSnapshot(teamName: string, snapshot: unkn
 export declare function readGjcMonitorSnapshot(teamName: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<unknown>;
 export declare function writeGjcTaskApproval(teamName: string, taskId: string, approval: Record<string, unknown>, cwd?: string, env?: NodeJS.ProcessEnv): Promise<Record<string, unknown>>;
 export declare function readGjcTaskApproval(teamName: string, taskId: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<Record<string, unknown> | null>;
-export declare function writeGjcShutdownRequest(teamName: string, worker: string, requestedBy: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<Record<string, unknown>>;
+export declare function writeGjcShutdownRequest(teamName: string, worker: string, requestedBy: string, cwd?: string, env?: NodeJS.ProcessEnv, requestId?: string, mode?: GjcTeamShutdownMode, requestedAt?: string): Promise<Record<string, unknown>>;
 export declare function readGjcShutdownAck(teamName: string, worker: string, cwd?: string, env?: NodeJS.ProcessEnv): Promise<Record<string, unknown> | null>;
 export declare function executeGjcTeamApiOperation(operation: string, input: Record<string, unknown>, cwd?: string, env?: NodeJS.ProcessEnv): Promise<unknown>;
 export declare function parseTeamLaunchArgs(argv: string[]): GjcTeamStartOptions;