astrocode-workflow 0.3.5 → 0.4.1

package/dist/src/tools/repair.js

@@ -1,25 +1,59 @@
+import path from "node:path";
 import { tool } from "@opencode-ai/plugin/tool";
 import { withTx } from "../state/db";
 import { repairState, formatRepairReport } from "../workflow/repair";
 import { putArtifact } from "../workflow/artifacts";
 import { nowISO } from "../shared/time";
+import { getLockStatus, tryRemoveStaleLock } from "../state/repo-lock";
 export function createAstroRepairTool(opts) {
     const { ctx, config, db } = opts;
     return tool({
-        description: "Repair Astrocode invariants and recover from inconsistent DB state. Writes a repair report artifact.",
+        description: "Repair Astrocode invariants and recover from inconsistent DB state. Also checks and repairs lock files. Writes a repair report artifact.",
         args: {
             write_report_artifact: tool.schema.boolean().default(true),
+            repair_lock: tool.schema.boolean().default(true).describe("Attempt to remove stale/dead lock files"),
         },
-        execute: async ({ write_report_artifact }) => {
+        execute: async ({ write_report_artifact, repair_lock }) => {
             const repoRoot = ctx.directory;
+            const lockPath = path.join(repoRoot, ".astro", "astro.lock");
+            // First, check and repair lock if requested
+            const lockLines = [];
+            const lockStatus = getLockStatus(lockPath);
+            if (lockStatus.exists) {
+                lockLines.push("## Lock Status");
+                lockLines.push(`- Lock found: ${lockPath}`);
+                lockLines.push(`- PID: ${lockStatus.pid} (${lockStatus.pidAlive ? 'alive' : 'dead'})`);
+                lockLines.push(`- Age: ${lockStatus.ageMs ? Math.floor(lockStatus.ageMs / 1000) : '?'}s`);
+                lockLines.push(`- Status: ${lockStatus.isStale ? 'stale' : 'fresh'}`);
+                if (repair_lock) {
+                    const result = tryRemoveStaleLock(lockPath);
+                    if (result.removed) {
+                        lockLines.push(`- **Removed**: ${result.reason}`);
+                    }
+                    else {
+                        lockLines.push(`- **Not removed**: ${result.reason}`);
+                    }
+                }
+                else {
+                    if (!lockStatus.pidAlive || lockStatus.isStale) {
+                        lockLines.push(`- **Recommendation**: Run with repair_lock=true to remove this ${!lockStatus.pidAlive ? 'dead' : 'stale'} lock`);
+                    }
+                }
+                lockLines.push("");
+            }
+            // Then repair database state
             const report = withTx(db, () => repairState(db, config));
-            const md = formatRepairReport(report);
+            const dbMd = formatRepairReport(report);
+            // Combine lock and DB repair
+            const fullMd = lockLines.length > 0
+                ? `# Astrocode Repair Report\n\n${lockLines.join("\n")}\n${dbMd.replace(/^# Astrocode repair report\n*/i, "")}`
+                : dbMd;
             if (write_report_artifact) {
                 const rel = `.astro/repair/repair_${nowISO().replace(/[:.]/g, "-")}.md`;
-                const a = putArtifact({ repoRoot, db, run_id: null, stage_key: null, type: "log", rel_path: rel, content: md, meta: { kind: "repair" } });
-                return md + `\n\nReport saved: ${rel} (artifact=${a.artifact_id})`;
+                const a = putArtifact({ repoRoot, db, run_id: null, stage_key: null, type: "log", rel_path: rel, content: fullMd, meta: { kind: "repair" } });
+                return fullMd + `\n\nReport saved: ${rel} (artifact=${a.artifact_id})`;
             }
-            return md;
+            return fullMd;
         },
     });
 }

package/dist/src/tools/workflow.js

@@ -166,6 +166,7 @@ export function createAstroWorkflowProceedTool(opts) {
                 repoRoot,
                 sessionId,
                 owner: "astro_workflow_proceed",
+                advisory: true, // Advisory mode: warn instead of blocking on lock contention
                 fn: async () => {
                     const steps = Math.min(max_steps, config.workflow.loop_max_steps_hard_cap);
                     const actions = [];

package/dist/src/workflow/repair.js

@@ -43,10 +43,10 @@ export function repairState(db, config) {
             .all(active.run_id);
         if (stageRuns.length < pipeline.length) {
             const existingKeys = new Set(stageRuns.map((s) => s.stage_key));
-            const insert = db.prepare("INSERT INTO stage_runs (stage_run_id, run_id, stage_key, stage_index, status, updated_at) VALUES (?, ?, ?, ?, 'pending', ?)");
+            const insert = db.prepare("INSERT INTO stage_runs (stage_run_id, run_id, stage_key, stage_index, status, created_at, updated_at) VALUES (?, ?, ?, ?, 'pending', ?, ?)");
             pipeline.forEach((key, idx) => {
                 if (!existingKeys.has(key)) {
-                    insert.run(newStageRunId(), active.run_id, key, idx, now);
+                    insert.run(newStageRunId(), active.run_id, key, idx, now, now);
                     push(report, `Inserted missing stage_run ${key} for run ${active.run_id}`);
                 }
             });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astrocode-workflow",
-  "version": "0.3.5",
+  "version": "0.4.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -20,7 +20,6 @@
   "dependencies": {
     "@opencode-ai/plugin": "^1.1.19",
     "@opencode-ai/sdk": "^1.1.19",
-    "astrocode-workflow": "^0.1.51",
     "jsonc-parser": "^3.2.0",
     "zod": "4.1.8"
   },

package/src/config/schema.ts

@@ -203,6 +203,7 @@ const InjectSchema = z
     scope_allowlist: z.array(z.string()).default(["repo", "global"]),
     type_allowlist: z.array(z.string()).default(["note", "policy"]),
     max_per_turn: z.number().int().positive().default(5),
+    auto_approve_queued_stories: z.boolean().default(false).describe("Auto-approve highest priority queued story after workflow tools"),
   })
   .partial()
   .default({});

package/src/hooks/inject-provider.ts

@@ -29,19 +29,30 @@ export function createInjectProvider(opts: {
   const { db } = runtime;
 
   // Cache to avoid re-injecting the same injects repeatedly
+  // Map of inject_id -> last injected timestamp
   const injectedCache = new Map<string, number>();
 
   function shouldSkipInject(injectId: string, nowMs: number): boolean {
     const lastInjected = injectedCache.get(injectId);
     if (!lastInjected) return false;
 
-    // Skip if injected within the last 5 minutes (configurable?)
-    const cooldownMs = 5 * 60 * 1000;
+    // REDUCED cooldown from 5 minutes to 1 minute
+    // This allows injects to appear more frequently during workflow
+    const cooldownMs = 1 * 60 * 1000;
     return nowMs - lastInjected < cooldownMs;
   }
 
   function markInjected(injectId: string, nowMs: number) {
     injectedCache.set(injectId, nowMs);
+
+    // Clean up old entries to prevent memory leak
+    // Remove entries older than 10 minutes
+    const tenMinutesAgo = nowMs - (10 * 60 * 1000);
+    for (const [id, timestamp] of injectedCache.entries()) {
+      if (timestamp < tenMinutesAgo) {
+        injectedCache.delete(id);
+      }
+    }
   }
 
   function getInjectionDiagnostics(nowIso: string, scopeAllowlist: string[], typeAllowlist: string[]): any {
@@ -94,7 +105,7 @@ export function createInjectProvider(opts: {
     };
   }
 
-  async function injectEligibleInjects(sessionId: string) {
+  async function injectEligibleInjects(sessionId: string, context?: string) {
     const now = nowISO();
     const nowMs = Date.now();
 
@@ -120,7 +131,7 @@ export function createInjectProvider(opts: {
       // Log when no injects are eligible
       if (EMIT_TELEMETRY) {
         // eslint-disable-next-line no-console
-        console.log(`[Astrocode:inject] ${now} selected=${diagnostics.selected_eligible} injected=0 skipped={expired:${diagnostics.skipped.expired} scope:${diagnostics.skipped.scope} type:${diagnostics.skipped.type} deduped:0}`);
+        console.log(`[Astrocode:inject] ${now} context=${context ?? 'unknown'} selected=0 injected=0 skipped={expired:${diagnostics.skipped.expired} scope:${diagnostics.skipped.scope} type:${diagnostics.skipped.type} deduped:0}`);
       }
       return;
     }
@@ -135,21 +146,68 @@ export function createInjectProvider(opts: {
       // Format as injection message
       const formattedText = `[Inject: ${inject.title}]\n\n${inject.body_md}`;
 
+      try {
+        await injectChatPrompt({
+          ctx,
+          sessionId,
+          text: formattedText,
+          agent: "Astrocode"
+        });
+
+        injected++;
+        markInjected(inject.inject_id, nowMs);
+      } catch (err) {
+        // Log injection failures but don't crash
+        // eslint-disable-next-line no-console
+        console.error(`[Astrocode:inject] Failed to inject ${inject.inject_id}:`, err);
+      }
+    }
+
+    // Log diagnostic summary
+    if (EMIT_TELEMETRY || injected > 0) {
+      // eslint-disable-next-line no-console
+      console.log(`[Astrocode:inject] ${now} context=${context ?? 'unknown'} selected=${diagnostics.selected_eligible} injected=${injected} skipped={expired:${diagnostics.skipped.expired} scope:${diagnostics.skipped.scope} type:${diagnostics.skipped.type} deduped:${skippedDeduped}}`);
+    }
+  }
+
+  // Workflow-related tools that should trigger inject + auto-approval
+  const WORKFLOW_TOOLS = new Set([
+    'astro_workflow_proceed',
+    'astro_story_queue',
+    'astro_story_approve',
+    'astro_stage_start',
+    'astro_stage_complete',
+    'astro_stage_fail',
+    'astro_run_abort',
+  ]);
+
+  // Auto-approve queued stories if enabled
+  async function maybeAutoApprove(sessionId: string) {
+    if (!config.inject?.auto_approve_queued_stories) return;
+
+    try {
+      // Get all queued stories
+      const queued = db.prepare("SELECT story_key, title FROM stories WHERE state='queued' ORDER BY priority DESC, created_at ASC").all() as Array<{ story_key: string; title: string }>;
+
+      if (queued.length === 0) return;
+
+      // Auto-approve the highest priority queued story
+      const story = queued[0];
+      db.prepare("UPDATE stories SET state='approved', updated_at=? WHERE story_key=?").run(nowISO(), story.story_key);
+
+      // eslint-disable-next-line no-console
+      console.log(`[Astrocode:inject] Auto-approved story ${story.story_key}: ${story.title}`);
+
+      // Inject a notification about the auto-approval
       await injectChatPrompt({
         ctx,
         sessionId,
-        text: formattedText,
+        text: `✅ Auto-approved story ${story.story_key}: ${story.title}`,
         agent: "Astrocode"
       });
-
-      injected++;
-      markInjected(inject.inject_id, nowMs);
-    }
-
-    // Log diagnostic summary
-    if (EMIT_TELEMETRY) {
+    } catch (err) {
       // eslint-disable-next-line no-console
-      console.log(`[Astrocode:inject] ${now} selected=${diagnostics.selected_eligible} injected=${injected} skipped={expired:${diagnostics.skipped.expired} scope:${diagnostics.skipped.scope} type:${diagnostics.skipped.type} deduped:${skippedDeduped}}`);
+      console.error(`[Astrocode:inject] Auto-approval failed:`, err);
     }
   }
 
@@ -159,18 +217,24 @@ export function createInjectProvider(opts: {
       if (!config.inject?.enabled) return;
 
       // Inject eligible injects before processing the user's message
-      await injectEligibleInjects(input.sessionID);
+      await injectEligibleInjects(input.sessionID, 'chat_message');
     },
 
     async onToolAfter(input: ToolExecuteAfterInput) {
       if (!config.inject?.enabled) return;
 
+      // Only inject after workflow-related tools
+      if (!WORKFLOW_TOOLS.has(input.tool)) return;
+
       // Extract sessionID (same pattern as continuation enforcer)
       const sessionId = input.sessionID ?? (ctx as any).sessionID;
       if (!sessionId) return;
 
-      // Inject eligible injects after tool execution
-      await injectEligibleInjects(sessionId);
+      // Auto-approve queued stories if enabled
+      await maybeAutoApprove(sessionId);
+
+      // Inject eligible injects after workflow tool execution
+      await injectEligibleInjects(sessionId, `tool_after:${input.tool}`);
     },
   };
 }

package/src/state/repo-lock.ts

@@ -272,29 +272,36 @@ function startHeartbeat(opts: {
     const shouldAttempt = now - lastWriteAt >= opts.minWriteMs;
 
     if (shouldAttempt) {
-      const existing = readLock(opts.lockPath);
-
-      if (
-        existing &&
-        existing.lease_id === opts.leaseId &&
-        existing.pid === (process as any).pid &&
-        existing.instance_id === PROCESS_INSTANCE_ID
-      ) {
-        const updatedMs = parseISOToMs(existing.updated_at);
-        const isFresh = updatedMs !== null && now - updatedMs < opts.minWriteMs;
-
-        if (!isFresh) {
-          writeLockAtomicish(opts.lockPath, {
-            ...existing,
-            updated_at: nowISO(),
-            repo_root: opts.repoRoot,
-            session_id: opts.sessionId ?? existing.session_id,
-            owner: opts.owner ?? existing.owner,
-          });
-          lastWriteAt = now;
-        } else {
-          lastWriteAt = now;
+      try {
+        const existing = readLock(opts.lockPath);
+
+        if (
+          existing &&
+          existing.lease_id === opts.leaseId &&
+          existing.pid === (process as any).pid &&
+          existing.instance_id === PROCESS_INSTANCE_ID
+        ) {
+          const updatedMs = parseISOToMs(existing.updated_at);
+          const isFresh = updatedMs !== null && now - updatedMs < opts.minWriteMs;
+
+          if (!isFresh) {
+            writeLockAtomicish(opts.lockPath, {
+              ...existing,
+              updated_at: nowISO(),
+              repo_root: opts.repoRoot,
+              session_id: opts.sessionId ?? existing.session_id,
+              owner: opts.owner ?? existing.owner,
+            });
+            lastWriteAt = now;
+          } else {
+            lastWriteAt = now;
+          }
         }
+      } catch (err) {
+        // Heartbeat write failed - don't propagate, just reschedule
+        // Lock will become stale if heartbeat continues failing
+        // eslint-disable-next-line no-console
+        console.warn("[Astrocode] Heartbeat write error:", err);
       }
     }
 
@@ -340,6 +347,18 @@ function installExitHookOnce() {
     cleanup();
     (process as any).exit(143);
   });
+  (process as any).once("uncaughtException", (err: any) => {
+    // eslint-disable-next-line no-console
+    console.error("[Astrocode] Uncaught Exception, cleaning up locks:", err);
+    cleanup();
+    (process as any).exit(1);
+  });
+  (process as any).once("unhandledRejection", (reason: any) => {
+    // eslint-disable-next-line no-console
+    console.error("[Astrocode] Unhandled Rejection, cleaning up locks:", reason);
+    cleanup();
+    (process as any).exit(1);
+  });
 }
 
 /**
@@ -596,4 +615,92 @@ export async function withRepoLock<T>(opts: {
   } finally {
     handle.release();
   }
+}
+
+/**
+ * Lock diagnostics and status information.
+ */
+export type LockStatus = {
+  exists: boolean;
+  path: string;
+  pid?: number;
+  pidAlive?: boolean;
+  instanceId?: string;
+  sessionId?: string;
+  owner?: string;
+  leaseId?: string;
+  createdAt?: string;
+  updatedAt?: string;
+  ageMs?: number;
+  isStale?: boolean;
+  repoRoot?: string;
+  version?: number;
+};
+
+/**
+ * Get lock file status and diagnostics.
+ * Returns detailed information about the current lock state.
+ */
+export function getLockStatus(lockPath: string, staleMs: number = 30_000): LockStatus {
+  const existing = readLock(lockPath);
+
+  if (!existing) {
+    return {
+      exists: false,
+      path: lockPath,
+    };
+  }
+
+  const updatedMs = parseISOToMs(existing.updated_at);
+  const ageMs = updatedMs !== null ? Date.now() - updatedMs : undefined;
+  const pidAlive = isPidAlive(existing.pid);
+  const isStale = isStaleByAge(existing, staleMs);
+
+  return {
+    exists: true,
+    path: lockPath,
+    pid: existing.pid,
+    pidAlive,
+    instanceId: existing.instance_id,
+    sessionId: existing.session_id,
+    owner: existing.owner,
+    leaseId: existing.lease_id,
+    createdAt: existing.created_at,
+    updatedAt: existing.updated_at,
+    ageMs,
+    isStale,
+    repoRoot: existing.repo_root,
+    version: existing.v,
+  };
+}
+
+/**
+ * Attempt to remove a lock file if it's safe to do so.
+ * Only removes locks with dead PIDs or stale timestamps.
+ * Returns true if lock was removed, false if lock is still held.
+ */
+export function tryRemoveStaleLock(lockPath: string, staleMs: number = 30_000): { removed: boolean; reason: string } {
+  const existing = readLock(lockPath);
+
+  if (!existing) {
+    return { removed: false, reason: "No lock file found" };
+  }
+
+  const pidAlive = isPidAlive(existing.pid);
+  const isStale = isStaleByAge(existing, staleMs);
+
+  if (!pidAlive) {
+    safeUnlink(lockPath);
+    fsyncDirBestEffort(path.dirname(lockPath));
+    return { removed: true, reason: `Dead PID ${existing.pid}` };
+  }
+
+  if (isStale) {
+    safeUnlink(lockPath);
+    fsyncDirBestEffort(path.dirname(lockPath));
+    const ageSeconds = Math.floor((Date.now() - (parseISOToMs(existing.updated_at) ?? 0)) / 1000);
+    return { removed: true, reason: `Stale lock (${ageSeconds}s old, threshold ${staleMs / 1000}s)` };
+  }
+
+  return { removed: false, reason: `Lock is active (PID ${existing.pid} alive, age ${Math.floor((Date.now() - (parseISOToMs(existing.updated_at) ?? 0)) / 1000)}s)` };
 }

package/src/state/schema.ts

@@ -4,7 +4,7 @@
 //
 // Source of truth: SQLite file at .astro/astro.db
 
-export const SCHEMA_VERSION = 2;
+export const SCHEMA_VERSION = 3; // v3: Added advisory lock support + database constraints
 
 export const SCHEMA_SQL = `
 PRAGMA foreign_keys = ON;
@@ -235,6 +235,13 @@ CREATE INDEX IF NOT EXISTS idx_artifacts_run_stage ON artifacts(run_id, stage_ke
 CREATE INDEX IF NOT EXISTS idx_events_run ON events(run_id, created_at DESC);
 CREATE INDEX IF NOT EXISTS idx_tool_runs_run ON tool_runs(run_id, created_at DESC);
 CREATE INDEX IF NOT EXISTS idx_injects_scope_priority ON injects(scope, priority DESC, created_at DESC);
+
+-- CONSTRAINT: Only one running run at a time (partial unique index)
+-- This provides database-level safety when using advisory locks
+CREATE UNIQUE INDEX IF NOT EXISTS idx_single_running_run ON runs(status) WHERE status = 'running';
+
+-- CONSTRAINT: Only one run can lock a story at a time (partial unique index)
+CREATE UNIQUE INDEX IF NOT EXISTS idx_single_story_lock ON stories(in_progress) WHERE in_progress = 1;
 CREATE INDEX IF NOT EXISTS idx_injects_scope_type_priority_updated ON injects(scope, type, priority DESC, updated_at DESC);
 CREATE INDEX IF NOT EXISTS idx_injects_expires ON injects(expires_at) WHERE expires_at IS NOT NULL;
 CREATE INDEX IF NOT EXISTS idx_injects_sha256 ON injects(sha256) WHERE sha256 IS NOT NULL;

package/src/state/workflow-repo-lock.ts

@@ -17,6 +17,12 @@ function key(lockPath: string, sessionId?: string) {
 /**
  * Acquire ONCE per workflow/session in this process.
  * Nested calls reuse the same held lock (no reacquire, no churn).
+ *
+ * ADVISORY LOCK MODE:
+ * - Creates lock file to signal other sessions
+ * - If lock held by another session: WARN and proceed anyway
+ * - Database constraints provide actual safety (single running run)
+ * - Better UX: no blocking, just helpful warnings
  */
 export async function workflowRepoLock<T>(
   deps: { acquireRepoLock: RepoLockAcquire },
@@ -26,6 +32,7 @@ export async function workflowRepoLock<T>(
     sessionId?: string;
     owner?: string;
     fn: () => Promise<T>;
+    advisory?: boolean; // If true, warn instead of error on contention
   }
 ): Promise<T> {
   const k = key(opts.lockPath, opts.sessionId);
@@ -45,19 +52,49 @@ export async function workflowRepoLock<T>(
   }
 
   // IMPORTANT: this is tuned for "hold for whole workflow".
-  const handle = await deps.acquireRepoLock({
-    lockPath: opts.lockPath,
-    repoRoot: opts.repoRoot,
-    sessionId: opts.sessionId,
-    owner: opts.owner,
+  let handle: { release: () => void } | null = null;
 
-    retryMs: 30_000,
-    staleMs: 2 * 60_000,
-    heartbeatMs: 200,
-    minWriteMs: 800,
-    pollMs: 20,
-    pollMaxMs: 250,
-  });
+  try {
+    handle = await deps.acquireRepoLock({
+      lockPath: opts.lockPath,
+      repoRoot: opts.repoRoot,
+      sessionId: opts.sessionId,
+      owner: opts.owner,
+
+      retryMs: opts.advisory ? 1000 : 30_000, // Advisory: fail fast, hard: wait longer
+      staleMs: 30_000, // Reduced from 2 minutes to 30 seconds for faster stale lock recovery
+      heartbeatMs: 200,
+      minWriteMs: 800,
+      pollMs: 20,
+      pollMaxMs: 250,
+    });
+  } catch (err: any) {
+    // Lock acquisition failed - check if advisory mode
+    if (opts.advisory) {
+      // Advisory mode: warn and proceed without lock
+      // eslint-disable-next-line no-console
+      console.warn(`⚠️  [Astrocode] Another session may be active. Proceeding anyway (advisory lock mode).`);
+      // eslint-disable-next-line no-console
+      console.warn(`    ${err.message}`);
+
+      // Proceed without lock - database constraints will ensure safety
+      try {
+        return await opts.fn();
+      } catch (dbErr: any) {
+        // Check if this is a concurrency error
+        if (dbErr.message?.includes('UNIQUE constraint') || dbErr.message?.includes('SQLITE_BUSY')) {
+          throw new Error(
+            `Another session is actively working on this story. Database prevented concurrent modification. ` +
+            `Please wait for the other session to complete, or work on a different story.`
+          );
+        }
+        throw dbErr;
+      }
+    }
+
+    // Hard lock mode: propagate error
+    throw err;
+  }
 
   const held: Held = { release: handle.release, depth: 1 };
   HELD_BY_KEY.set(k, held);

package/src/tools/index.ts

@@ -15,6 +15,7 @@ import { createAstroRepairTool } from "./repair";
 import { createAstroHealthTool } from "./health";
 import { createAstroResetTool } from "./reset";
 import { createAstroMetricsTool } from "./metrics";
+import { createAstroLockStatusTool } from "./lock";
 
 import { AgentConfig } from "@opencode-ai/sdk";
 
@@ -44,6 +45,7 @@ export function createAstroTools(opts: CreateAstroToolsOptions): Record<string,
      tools.astro_health = createAstroHealthTool({ ctx, config, db });
      tools.astro_reset = createAstroResetTool({ ctx, config, db });
      tools.astro_metrics = createAstroMetricsTool({ ctx, config });
+     tools.astro_lock_status = createAstroLockStatusTool({ ctx });
 
    // Recovery tool - available even in limited mode to allow DB initialization
    tools.astro_init = createAstroInitTool({ ctx, config, runtime });
@@ -109,6 +111,7 @@ export function createAstroTools(opts: CreateAstroToolsOptions): Record<string,
      ["_astro_health", "astro_health"],
      ["_astro_reset", "astro_reset"],
      ["_astro_metrics", "astro_metrics"],
+     ["_astro_lock_status", "astro_lock_status"],
   ];
 
   // Only add aliases for tools that exist

package/src/tools/lock.ts

@@ -0,0 +1,75 @@
+import path from "node:path";
+import { tool, type ToolDefinition } from "@opencode-ai/plugin/tool";
+import { getLockStatus, tryRemoveStaleLock } from "../state/repo-lock";
+
+export function createAstroLockStatusTool(opts: { ctx: any }): ToolDefinition {
+  const { ctx } = opts;
+
+  return tool({
+    description: "Check Astrocode lock status and attempt repair. Shows diagnostics (PID, age, session) and can remove stale/dead locks.",
+    args: {
+      attempt_repair: tool.schema.boolean().default(false).describe("If true, attempt to remove stale or dead locks"),
+    },
+    execute: async ({ attempt_repair }) => {
+      const repoRoot = ctx.directory as string;
+      const lockPath = path.join(repoRoot, ".astro", "astro.lock");
+
+      const status = getLockStatus(lockPath);
+
+      if (!status.exists) {
+        return "✅ No lock file found. Repository is unlocked.";
+      }
+
+      const lines: string[] = [];
+      lines.push("# Astrocode Lock Status");
+      lines.push("");
+      lines.push("## Lock Details");
+      lines.push(`- **Path**: ${status.path}`);
+      lines.push(`- **PID**: ${status.pid} (${status.pidAlive ? '🟢 ALIVE' : '🔴 DEAD'})`);
+      lines.push(`- **Age**: ${status.ageMs ? Math.floor(status.ageMs / 1000) : '?'}s`);
+      lines.push(`- **Status**: ${status.isStale ? '⚠️ STALE' : '✅ FRESH'}`);
+      if (status.sessionId) lines.push(`- **Session**: ${status.sessionId}`);
+      if (status.owner) lines.push(`- **Owner**: ${status.owner}`);
+      if (status.instanceId) lines.push(`- **Instance**: ${status.instanceId.substring(0, 8)}...`);
+      if (status.leaseId) lines.push(`- **Lease**: ${status.leaseId.substring(0, 8)}...`);
+      if (status.createdAt) lines.push(`- **Created**: ${status.createdAt}`);
+      if (status.updatedAt) lines.push(`- **Updated**: ${status.updatedAt}`);
+      if (status.repoRoot) lines.push(`- **Repo**: ${status.repoRoot}`);
+      lines.push(`- **Version**: ${status.version ?? 'unknown'}`);
+      lines.push("");
+
+      if (attempt_repair) {
+        lines.push("## Repair Attempt");
+        const result = tryRemoveStaleLock(lockPath);
+
+        if (result.removed) {
+          lines.push(`✅ **Lock removed**: ${result.reason}`);
+          lines.push("");
+          lines.push("The repository is now unlocked and ready for use.");
+        } else {
+          lines.push(`⚠️ **Lock NOT removed**: ${result.reason}`);
+          lines.push("");
+          lines.push("**Recommendations**:");
+          lines.push("- If the owning process has crashed, wait 30 seconds for automatic stale detection");
+          lines.push("- If the process is still running, wait for it to complete");
+          lines.push("- As a last resort, manually stop the process and run this tool again with attempt_repair=true");
+        }
+      } else {
+        lines.push("## Recommendations");
+        if (!status.pidAlive) {
+          lines.push("🔧 **Action Required**: Lock belongs to dead process. Run with `attempt_repair=true` to remove it.");
+        } else if (status.isStale) {
+          lines.push("🔧 **Action Suggested**: Lock is stale (not updated recently). Run with `attempt_repair=true` to remove it.");
+        } else {
+          lines.push("✅ Lock is active and healthy. The owning process is running normally.");
+          lines.push("");
+          lines.push("If you believe this is incorrect:");
+          lines.push("- Wait 30 seconds and check again (automatic stale detection)");
+          lines.push("- Run with `attempt_repair=true` only if you're certain the process has crashed");
+        }
+      }
+
+      return lines.join("\n");
+    },
+  });
+}