astrocode-workflow 0.3.5 → 0.4.1

package/dist/src/config/schema.d.ts

@@ -183,6 +183,7 @@ export declare const AstrocodeConfigSchema: z.ZodDefault<z.ZodObject<{
         scope_allowlist: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
         type_allowlist: z.ZodOptional<z.ZodDefault<z.ZodArray<z.ZodString>>>;
         max_per_turn: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+        auto_approve_queued_stories: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
     }, z.core.$strip>>>;
     debug: z.ZodOptional<z.ZodDefault<z.ZodObject<{
         telemetry: z.ZodOptional<z.ZodDefault<z.ZodObject<{

package/dist/src/config/schema.js

@@ -169,6 +169,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/dist/src/hooks/inject-provider.js

@@ -5,17 +5,27 @@ export function createInjectProvider(opts) {
     const { ctx, config, runtime } = opts;
     const { db } = runtime;
     // Cache to avoid re-injecting the same injects repeatedly
+    // Map of inject_id -> last injected timestamp
     const injectedCache = new Map();
     function shouldSkipInject(injectId, nowMs) {
         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, nowMs) {
         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, scopeAllowlist, typeAllowlist) {
         // Get ALL injects to analyze filtering
@@ -60,7 +70,7 @@ export function createInjectProvider(opts) {
             eligible_ids: eligibleIds,
         };
     }
-    async function injectEligibleInjects(sessionId) {
+    async function injectEligibleInjects(sessionId, context) {
         const now = nowISO();
         const nowMs = Date.now();
         // Get allowlists from config or defaults
@@ -81,7 +91,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;
         }
@@ -93,19 +103,63 @@ 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) {
+        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();
+            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);
         }
     }
     // Public hook handlers
@@ -114,17 +168,22 @@ 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) {
             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.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/dist/src/state/repo-lock.d.ts

@@ -32,3 +32,36 @@ export declare function withRepoLock<T>(opts: {
     owner?: string;
     fn: () => Promise<T>;
 }): Promise<T>;
+/**
+ * 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 declare function getLockStatus(lockPath: string, staleMs?: number): LockStatus;
+/**
+ * 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 declare function tryRemoveStaleLock(lockPath: string, staleMs?: number): {
+    removed: boolean;
+    reason: string;
+};

package/dist/src/state/repo-lock.js

@@ -222,27 +222,35 @@ function startHeartbeat(opts) {
         const now = Date.now();
         const shouldAttempt = now - lastWriteAt >= opts.minWriteMs;
         if (shouldAttempt) {
-            const existing = readLock(opts.lockPath);
-            if (existing &&
-                existing.lease_id === opts.leaseId &&
-                existing.pid === process.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.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);
+            }
         }
         timer = setTimeout(tick, opts.heartbeatMs);
         timer.unref?.();
@@ -284,6 +292,18 @@ function installExitHookOnce() {
         cleanup();
         process.exit(143);
     });
+    process.once("uncaughtException", (err) => {
+        // eslint-disable-next-line no-console
+        console.error("[Astrocode] Uncaught Exception, cleaning up locks:", err);
+        cleanup();
+        process.exit(1);
+    });
+    process.once("unhandledRejection", (reason) => {
+        // eslint-disable-next-line no-console
+        console.error("[Astrocode] Unhandled Rejection, cleaning up locks:", reason);
+        cleanup();
+        process.exit(1);
+    });
 }
 /**
  * Acquire a repo-scoped lock with:
@@ -500,3 +520,61 @@ export async function withRepoLock(opts) {
         handle.release();
     }
 }
+/**
+ * Get lock file status and diagnostics.
+ * Returns detailed information about the current lock state.
+ */
+export function getLockStatus(lockPath, staleMs = 30_000) {
+    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, staleMs = 30_000) {
+    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/dist/src/state/schema.d.ts

@@ -1,2 +1,2 @@
-export declare const SCHEMA_VERSION = 2;
-export declare const SCHEMA_SQL = "\nPRAGMA foreign_keys = ON;\n\nCREATE TABLE IF NOT EXISTS repo_state (\n  id INTEGER PRIMARY KEY CHECK (id = 1),\n  schema_version INTEGER NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  spec_hash_before TEXT,\n  spec_hash_after TEXT,\n  last_run_id TEXT,\n  last_story_key TEXT,\n  last_event_at TEXT\n);\n\nCREATE TABLE IF NOT EXISTS settings (\n  key TEXT PRIMARY KEY,\n  value TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS epics (\n  epic_key TEXT PRIMARY KEY,\n  title TEXT NOT NULL,\n  body_md TEXT NOT NULL DEFAULT '',\n  state TEXT NOT NULL DEFAULT 'active',\n  priority INTEGER NOT NULL DEFAULT 0,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS story_drafts (\n  draft_id TEXT PRIMARY KEY,\n  title TEXT NOT NULL,\n  body_md TEXT NOT NULL DEFAULT '',\n  meta_json TEXT NOT NULL DEFAULT '{}',\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS story_keyseq (\n  id INTEGER PRIMARY KEY CHECK (id = 1),\n  next_story_num INTEGER NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS stories (\n  story_key TEXT PRIMARY KEY,\n  epic_key TEXT,\n  title TEXT NOT NULL,\n  body_md TEXT NOT NULL DEFAULT '',\n  state TEXT NOT NULL DEFAULT 'queued', -- queued|approved|in_progress|done|blocked|archived\n  priority INTEGER NOT NULL DEFAULT 0,\n  approved_at TEXT,\n  locked_by_run_id TEXT,\n  locked_at TEXT,\n  in_progress INTEGER NOT NULL DEFAULT 0,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  FOREIGN KEY (epic_key) REFERENCES epics(epic_key)\n);\n\nCREATE TABLE IF NOT EXISTS runs (\n  run_id TEXT PRIMARY KEY,\n  story_key TEXT NOT NULL,\n  status TEXT NOT NULL DEFAULT 'created', -- created|running|completed|failed|aborted\n  pipeline_stages_json TEXT NOT NULL DEFAULT '[]',\n  current_stage_key TEXT,\n  created_at TEXT NOT NULL,\n  started_at TEXT,\n  completed_at TEXT,\n  updated_at TEXT NOT NULL,\n  error_text TEXT,\n  FOREIGN KEY (story_key) REFERENCES stories(story_key)\n);\n\nCREATE TABLE IF NOT EXISTS stage_runs (\n  stage_run_id TEXT PRIMARY KEY,\n  run_id TEXT NOT NULL,\n  stage_key TEXT NOT NULL,\n  stage_index INTEGER NOT NULL,\n  status TEXT NOT NULL DEFAULT 'pending', -- pending|running|completed|failed|skipped\n  created_at TEXT NOT NULL,\n  subagent_type TEXT,\n  subagent_session_id TEXT,\n  started_at TEXT,\n  completed_at TEXT,\n  updated_at TEXT NOT NULL,\n  baton_path TEXT,\n  summary_md TEXT,\n  output_json TEXT,\n  error_text TEXT,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS artifacts (\n  artifact_id TEXT PRIMARY KEY,\n  run_id TEXT,\n  stage_key TEXT,\n  type TEXT NOT NULL, -- plan|baton|evidence|diff|log|summary|commit|tool_output|snapshot\n  path TEXT NOT NULL,\n  sha256 TEXT,\n  meta_json TEXT NOT NULL DEFAULT '{}',\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS tool_runs (\n  tool_run_id TEXT PRIMARY KEY,\n  run_id TEXT,\n  stage_key TEXT,\n  tool_name TEXT NOT NULL,\n  args_json TEXT NOT NULL DEFAULT '{}',\n  output_summary TEXT NOT NULL DEFAULT '',\n  output_artifact_id TEXT,\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS events (\n  event_id TEXT PRIMARY KEY,\n  run_id TEXT,\n  stage_key TEXT,\n  type TEXT NOT NULL,\n  body_json TEXT NOT NULL DEFAULT '{}',\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS injects (\n  inject_id TEXT PRIMARY KEY,\n  type TEXT NOT NULL DEFAULT 'note',\n  title TEXT NOT NULL,\n  body_md TEXT NOT NULL,\n  tags_json TEXT NOT NULL DEFAULT '[]',\n  scope TEXT NOT NULL DEFAULT 'repo', -- repo|run:<id>|story:<key>|global\n  source TEXT NOT NULL DEFAULT 'user', -- user|tool|agent|import\n  priority INTEGER NOT NULL DEFAULT 50,\n  expires_at TEXT,\n  sha256 TEXT,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS running_batches (\n  batch_id TEXT PRIMARY KEY,\n  run_id TEXT,\n  session_id TEXT,\n  status TEXT NOT NULL DEFAULT 'running', -- running|completed|failed|aborted\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS workflow_metrics (\n  metric_id TEXT PRIMARY KEY,\n  run_id TEXT,\n  stage_key TEXT,\n  name TEXT NOT NULL,\n  value_num REAL,\n  value_text TEXT,\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS template_intents (\n  intent_key TEXT PRIMARY KEY,\n  body_md TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\n-- vNext tables\n\nCREATE TABLE IF NOT EXISTS story_relations (\n  parent_story_key TEXT NOT NULL,\n  child_story_key TEXT NOT NULL,\n  relation_type TEXT NOT NULL DEFAULT 'split',\n  reason TEXT NOT NULL DEFAULT '',\n  created_at TEXT NOT NULL,\n  PRIMARY KEY (parent_story_key, child_story_key),\n  FOREIGN KEY (parent_story_key) REFERENCES stories(story_key),\n  FOREIGN KEY (child_story_key) REFERENCES stories(story_key)\n);\n\nCREATE TABLE IF NOT EXISTS continuations (\n  continuation_id INTEGER PRIMARY KEY AUTOINCREMENT,\n  session_id TEXT NOT NULL,\n  run_id TEXT,\n  directive_hash TEXT NOT NULL,\n  kind TEXT NOT NULL, -- continue|stage|blocked|repair\n  reason TEXT NOT NULL DEFAULT '',\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_continuations_session_created ON continuations(session_id, created_at DESC);\nCREATE INDEX IF NOT EXISTS idx_continuations_run_created ON continuations(run_id, created_at DESC);\n\nCREATE TABLE IF NOT EXISTS context_snapshots (\n  snapshot_id TEXT PRIMARY KEY,\n  run_id TEXT NOT NULL,\n  stage_key TEXT NOT NULL,\n  summary_md TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_context_snapshots_run_created ON context_snapshots(run_id, created_at DESC);\n\nCREATE TABLE IF NOT EXISTS agent_sessions (\n  session_id TEXT PRIMARY KEY,\n  parent_session_id TEXT,\n  agent_name TEXT NOT NULL,\n  run_id TEXT,\n  stage_key TEXT,\n  status TEXT NOT NULL DEFAULT 'active',\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\n-- Indexes\n\nCREATE INDEX IF NOT EXISTS idx_stories_state ON stories(state);\nCREATE INDEX IF NOT EXISTS idx_runs_story ON runs(story_key);\nCREATE INDEX IF NOT EXISTS idx_runs_status ON runs(status);\nCREATE INDEX IF NOT EXISTS idx_stage_runs_run ON stage_runs(run_id, stage_index);\nCREATE INDEX IF NOT EXISTS idx_artifacts_run_stage ON artifacts(run_id, stage_key, created_at DESC);\nCREATE INDEX IF NOT EXISTS idx_events_run ON events(run_id, created_at DESC);\nCREATE INDEX IF NOT EXISTS idx_tool_runs_run ON tool_runs(run_id, created_at DESC);\nCREATE INDEX IF NOT EXISTS idx_injects_scope_priority ON injects(scope, priority DESC, created_at DESC);\nCREATE INDEX IF NOT EXISTS idx_injects_scope_type_priority_updated ON injects(scope, type, priority DESC, updated_at DESC);\nCREATE INDEX IF NOT EXISTS idx_injects_expires ON injects(expires_at) WHERE expires_at IS NOT NULL;\nCREATE INDEX IF NOT EXISTS idx_injects_sha256 ON injects(sha256) WHERE sha256 IS NOT NULL;\n\n-- Stronger invariants (SQLite partial indexes)\n-- Only one run may be 'running' at a time (single-repo harness by default).\nCREATE UNIQUE INDEX IF NOT EXISTS uniq_single_running_run\n  ON runs(status)\n  WHERE status = 'running';\n\n-- Only one story may be in_progress=1 at a time (pairs with single running run).\nCREATE UNIQUE INDEX IF NOT EXISTS uniq_single_in_progress_story\n  ON stories(in_progress)\n  WHERE in_progress = 1;\n\n";
+export declare const SCHEMA_VERSION = 3;
+export declare const SCHEMA_SQL = "\nPRAGMA foreign_keys = ON;\n\nCREATE TABLE IF NOT EXISTS repo_state (\n  id INTEGER PRIMARY KEY CHECK (id = 1),\n  schema_version INTEGER NOT NULL,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  spec_hash_before TEXT,\n  spec_hash_after TEXT,\n  last_run_id TEXT,\n  last_story_key TEXT,\n  last_event_at TEXT\n);\n\nCREATE TABLE IF NOT EXISTS settings (\n  key TEXT PRIMARY KEY,\n  value TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS epics (\n  epic_key TEXT PRIMARY KEY,\n  title TEXT NOT NULL,\n  body_md TEXT NOT NULL DEFAULT '',\n  state TEXT NOT NULL DEFAULT 'active',\n  priority INTEGER NOT NULL DEFAULT 0,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS story_drafts (\n  draft_id TEXT PRIMARY KEY,\n  title TEXT NOT NULL,\n  body_md TEXT NOT NULL DEFAULT '',\n  meta_json TEXT NOT NULL DEFAULT '{}',\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS story_keyseq (\n  id INTEGER PRIMARY KEY CHECK (id = 1),\n  next_story_num INTEGER NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS stories (\n  story_key TEXT PRIMARY KEY,\n  epic_key TEXT,\n  title TEXT NOT NULL,\n  body_md TEXT NOT NULL DEFAULT '',\n  state TEXT NOT NULL DEFAULT 'queued', -- queued|approved|in_progress|done|blocked|archived\n  priority INTEGER NOT NULL DEFAULT 0,\n  approved_at TEXT,\n  locked_by_run_id TEXT,\n  locked_at TEXT,\n  in_progress INTEGER NOT NULL DEFAULT 0,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  FOREIGN KEY (epic_key) REFERENCES epics(epic_key)\n);\n\nCREATE TABLE IF NOT EXISTS runs (\n  run_id TEXT PRIMARY KEY,\n  story_key TEXT NOT NULL,\n  status TEXT NOT NULL DEFAULT 'created', -- created|running|completed|failed|aborted\n  pipeline_stages_json TEXT NOT NULL DEFAULT '[]',\n  current_stage_key TEXT,\n  created_at TEXT NOT NULL,\n  started_at TEXT,\n  completed_at TEXT,\n  updated_at TEXT NOT NULL,\n  error_text TEXT,\n  FOREIGN KEY (story_key) REFERENCES stories(story_key)\n);\n\nCREATE TABLE IF NOT EXISTS stage_runs (\n  stage_run_id TEXT PRIMARY KEY,\n  run_id TEXT NOT NULL,\n  stage_key TEXT NOT NULL,\n  stage_index INTEGER NOT NULL,\n  status TEXT NOT NULL DEFAULT 'pending', -- pending|running|completed|failed|skipped\n  created_at TEXT NOT NULL,\n  subagent_type TEXT,\n  subagent_session_id TEXT,\n  started_at TEXT,\n  completed_at TEXT,\n  updated_at TEXT NOT NULL,\n  baton_path TEXT,\n  summary_md TEXT,\n  output_json TEXT,\n  error_text TEXT,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS artifacts (\n  artifact_id TEXT PRIMARY KEY,\n  run_id TEXT,\n  stage_key TEXT,\n  type TEXT NOT NULL, -- plan|baton|evidence|diff|log|summary|commit|tool_output|snapshot\n  path TEXT NOT NULL,\n  sha256 TEXT,\n  meta_json TEXT NOT NULL DEFAULT '{}',\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS tool_runs (\n  tool_run_id TEXT PRIMARY KEY,\n  run_id TEXT,\n  stage_key TEXT,\n  tool_name TEXT NOT NULL,\n  args_json TEXT NOT NULL DEFAULT '{}',\n  output_summary TEXT NOT NULL DEFAULT '',\n  output_artifact_id TEXT,\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS events (\n  event_id TEXT PRIMARY KEY,\n  run_id TEXT,\n  stage_key TEXT,\n  type TEXT NOT NULL,\n  body_json TEXT NOT NULL DEFAULT '{}',\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS injects (\n  inject_id TEXT PRIMARY KEY,\n  type TEXT NOT NULL DEFAULT 'note',\n  title TEXT NOT NULL,\n  body_md TEXT NOT NULL,\n  tags_json TEXT NOT NULL DEFAULT '[]',\n  scope TEXT NOT NULL DEFAULT 'repo', -- repo|run:<id>|story:<key>|global\n  source TEXT NOT NULL DEFAULT 'user', -- user|tool|agent|import\n  priority INTEGER NOT NULL DEFAULT 50,\n  expires_at TEXT,\n  sha256 TEXT,\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\nCREATE TABLE IF NOT EXISTS running_batches (\n  batch_id TEXT PRIMARY KEY,\n  run_id TEXT,\n  session_id TEXT,\n  status TEXT NOT NULL DEFAULT 'running', -- running|completed|failed|aborted\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS workflow_metrics (\n  metric_id TEXT PRIMARY KEY,\n  run_id TEXT,\n  stage_key TEXT,\n  name TEXT NOT NULL,\n  value_num REAL,\n  value_text TEXT,\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE TABLE IF NOT EXISTS template_intents (\n  intent_key TEXT PRIMARY KEY,\n  body_md TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\n-- vNext tables\n\nCREATE TABLE IF NOT EXISTS story_relations (\n  parent_story_key TEXT NOT NULL,\n  child_story_key TEXT NOT NULL,\n  relation_type TEXT NOT NULL DEFAULT 'split',\n  reason TEXT NOT NULL DEFAULT '',\n  created_at TEXT NOT NULL,\n  PRIMARY KEY (parent_story_key, child_story_key),\n  FOREIGN KEY (parent_story_key) REFERENCES stories(story_key),\n  FOREIGN KEY (child_story_key) REFERENCES stories(story_key)\n);\n\nCREATE TABLE IF NOT EXISTS continuations (\n  continuation_id INTEGER PRIMARY KEY AUTOINCREMENT,\n  session_id TEXT NOT NULL,\n  run_id TEXT,\n  directive_hash TEXT NOT NULL,\n  kind TEXT NOT NULL, -- continue|stage|blocked|repair\n  reason TEXT NOT NULL DEFAULT '',\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_continuations_session_created ON continuations(session_id, created_at DESC);\nCREATE INDEX IF NOT EXISTS idx_continuations_run_created ON continuations(run_id, created_at DESC);\n\nCREATE TABLE IF NOT EXISTS context_snapshots (\n  snapshot_id TEXT PRIMARY KEY,\n  run_id TEXT NOT NULL,\n  stage_key TEXT NOT NULL,\n  summary_md TEXT NOT NULL,\n  created_at TEXT NOT NULL,\n  FOREIGN KEY (run_id) REFERENCES runs(run_id)\n);\n\nCREATE INDEX IF NOT EXISTS idx_context_snapshots_run_created ON context_snapshots(run_id, created_at DESC);\n\nCREATE TABLE IF NOT EXISTS agent_sessions (\n  session_id TEXT PRIMARY KEY,\n  parent_session_id TEXT,\n  agent_name TEXT NOT NULL,\n  run_id TEXT,\n  stage_key TEXT,\n  status TEXT NOT NULL DEFAULT 'active',\n  created_at TEXT NOT NULL,\n  updated_at TEXT NOT NULL\n);\n\n-- Indexes\n\nCREATE INDEX IF NOT EXISTS idx_stories_state ON stories(state);\nCREATE INDEX IF NOT EXISTS idx_runs_story ON runs(story_key);\nCREATE INDEX IF NOT EXISTS idx_runs_status ON runs(status);\nCREATE INDEX IF NOT EXISTS idx_stage_runs_run ON stage_runs(run_id, stage_index);\nCREATE INDEX IF NOT EXISTS idx_artifacts_run_stage ON artifacts(run_id, stage_key, created_at DESC);\nCREATE INDEX IF NOT EXISTS idx_events_run ON events(run_id, created_at DESC);\nCREATE INDEX IF NOT EXISTS idx_tool_runs_run ON tool_runs(run_id, created_at DESC);\nCREATE INDEX IF NOT EXISTS idx_injects_scope_priority ON injects(scope, priority DESC, created_at DESC);\n\n-- CONSTRAINT: Only one running run at a time (partial unique index)\n-- This provides database-level safety when using advisory locks\nCREATE UNIQUE INDEX IF NOT EXISTS idx_single_running_run ON runs(status) WHERE status = 'running';\n\n-- CONSTRAINT: Only one run can lock a story at a time (partial unique index)\nCREATE UNIQUE INDEX IF NOT EXISTS idx_single_story_lock ON stories(in_progress) WHERE in_progress = 1;\nCREATE INDEX IF NOT EXISTS idx_injects_scope_type_priority_updated ON injects(scope, type, priority DESC, updated_at DESC);\nCREATE INDEX IF NOT EXISTS idx_injects_expires ON injects(expires_at) WHERE expires_at IS NOT NULL;\nCREATE INDEX IF NOT EXISTS idx_injects_sha256 ON injects(sha256) WHERE sha256 IS NOT NULL;\n\n-- Stronger invariants (SQLite partial indexes)\n-- Only one run may be 'running' at a time (single-repo harness by default).\nCREATE UNIQUE INDEX IF NOT EXISTS uniq_single_running_run\n  ON runs(status)\n  WHERE status = 'running';\n\n-- Only one story may be in_progress=1 at a time (pairs with single running run).\nCREATE UNIQUE INDEX IF NOT EXISTS uniq_single_in_progress_story\n  ON stories(in_progress)\n  WHERE in_progress = 1;\n\n";

package/dist/src/state/schema.js

@@ -3,7 +3,7 @@
 // vNext adds continuation/snapshot/session tables and stronger indexes.
 //
 // 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;
 
@@ -233,6 +233,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/dist/src/state/workflow-repo-lock.d.ts

@@ -3,6 +3,12 @@ type RepoLockAcquire = typeof acquireRepoLock;
 /**
  * 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 declare function workflowRepoLock<T>(deps: {
     acquireRepoLock: RepoLockAcquire;
@@ -12,5 +18,6 @@ export declare function workflowRepoLock<T>(deps: {
     sessionId?: string;
     owner?: string;
     fn: () => Promise<T>;
+    advisory?: boolean;
 }): Promise<T>;
 export {};

package/dist/src/state/workflow-repo-lock.js

@@ -5,6 +5,12 @@ function key(lockPath, sessionId) {
 /**
  * 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(deps, opts) {
     const k = key(opts.lockPath, opts.sessionId);
@@ -23,18 +29,45 @@ export async function workflowRepoLock(deps, opts) {
         }
     }
     // 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,
-        retryMs: 30_000,
-        staleMs: 2 * 60_000,
-        heartbeatMs: 200,
-        minWriteMs: 800,
-        pollMs: 20,
-        pollMaxMs: 250,
-    });
+    let handle = null;
+    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) {
+        // 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) {
+                // 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 = { release: handle.release, depth: 1 };
     HELD_BY_KEY.set(k, held);
     try {

package/dist/src/tools/index.js

@@ -11,6 +11,7 @@ import { createAstroRepairTool } from "./repair";
 import { createAstroHealthTool } from "./health";
 import { createAstroResetTool } from "./reset";
 import { createAstroMetricsTool } from "./metrics";
+import { createAstroLockStatusTool } from "./lock";
 export function createAstroTools(opts) {
     const { ctx, config, agents, runtime } = opts;
     const { db } = runtime;
@@ -22,6 +23,7 @@ export function createAstroTools(opts) {
     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 });
     // Database-dependent tools
@@ -83,6 +85,7 @@ export function createAstroTools(opts) {
         ["_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
     for (const [alias, target] of aliases) {

package/dist/src/tools/lock.d.ts

@@ -0,0 +1,4 @@
+import { type ToolDefinition } from "@opencode-ai/plugin/tool";
+export declare function createAstroLockStatusTool(opts: {
+    ctx: any;
+}): ToolDefinition;

package/dist/src/tools/lock.js

@@ -0,0 +1,78 @@
+import path from "node:path";
+import { tool } from "@opencode-ai/plugin/tool";
+import { getLockStatus, tryRemoveStaleLock } from "../state/repo-lock";
+export function createAstroLockStatusTool(opts) {
+    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;
+            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 = [];
+            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");
+        },
+    });
+}