@agentic-workflow-kit/orchestrator 0.1.0

package/dist/config/schema.js

@@ -0,0 +1,80 @@
+import { z } from 'zod';
+const nonEmpty = z.string().min(1);
+export const ConfigSchema = z
+    .object({
+    version: z.literal(1),
+    paths: z
+        .object({
+        tracksDir: nonEmpty.default('docs/tracks'),
+        specsDir: nonEmpty.default('docs/specs'),
+        plansDir: nonEmpty.default('docs/plans'),
+        archiveDir: nonEmpty.default('docs/tracks/archive'),
+        prdsDir: nonEmpty.default('docs/prds'),
+    })
+        .strict()
+        .prefault({}),
+    statuses: z
+        .object({
+        eligible: z.array(nonEmpty).min(1).default(['specced', 'plan-approved']),
+        inProgress: nonEmpty.default('implementing'),
+        complete: z.array(nonEmpty).min(1).default(['done', 'verified']),
+    })
+        .strict()
+        .prefault({}),
+    tracker: z
+        .object({ idPattern: nonEmpty.default('^[A-Z]{2,}[0-9]+$') })
+        .strict()
+        .prefault({}),
+    verify: z
+        .object({
+        changed: nonEmpty.nullable().default(null),
+        full: nonEmpty.nullable().default(null),
+    })
+        .strict()
+        .prefault({}),
+    git: z
+        .object({
+        strategy: z.enum(['worktree', 'branch']).default('worktree'),
+        branchPattern: nonEmpty.default('{track}/{id-lc}-{slug}'),
+        baseBranch: nonEmpty.default('main'),
+        commitOnBase: z.enum(['forbid', 'allow']).default('forbid'),
+    })
+        .strict()
+        .prefault({}),
+    pr: z
+        .object({
+        create: z.boolean().default(true),
+        ci: z
+            .object({ wait: z.boolean().default(false), command: nonEmpty.nullable().default(null) })
+            .strict()
+            .prefault({}),
+        review: z
+            .object({
+            wait: z.enum(['none', 'bot', 'human']).default('none'),
+            bot: nonEmpty.default('none'),
+            triageComments: z.boolean().default(false),
+        })
+            .strict()
+            .prefault({}),
+        merge: z
+            .object({
+            auto: z.boolean().default(false),
+            method: z.enum(['squash', 'merge', 'rebase']).default('squash'),
+            deleteBranch: z.boolean().default(true),
+        })
+            .strict()
+            .prefault({}),
+    })
+        .strict()
+        .prefault({}),
+    orchestrator: z
+        .object({
+        driver: nonEmpty.default('codex-mcp'),
+        maxParallel: z.number().int().min(1).default(2),
+        stopLaunchingOnBlocked: z.boolean().default(true),
+        childTimeoutMs: z.number().int().min(1).default(1_800_000),
+    })
+        .strict()
+        .prefault({}),
+})
+    .strict();

package/dist/drivers/StoryRunner.d.ts

@@ -0,0 +1,24 @@
+import type { ChildMetricsSnapshot, WorkflowStory } from '../types.js';
+export interface StoryRunRequest {
+    story: WorkflowStory;
+    prompt: string;
+    cwd: string;
+    metadata: Record<string, unknown>;
+}
+export interface StoryRunResult {
+    storyId: string;
+    sessionId: string | null;
+    content: string;
+    rawResult: unknown;
+    invocation: Record<string, unknown>;
+    metrics?: ChildMetricsSnapshot;
+}
+export interface DriverToolStatus {
+    ok: boolean;
+    tools: string[];
+}
+export interface StoryRunner {
+    runStory(request: StoryRunRequest): Promise<StoryRunResult>;
+    checkTools(): Promise<DriverToolStatus>;
+}
+//# sourceMappingURL=StoryRunner.d.ts.map

package/dist/drivers/StoryRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StoryRunner.d.ts","sourceRoot":"","sources":["../../src/drivers/StoryRunner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEvE,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,aAAa,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACpC,OAAO,CAAC,EAAE,oBAAoB,CAAC;CAChC;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAC5D,UAAU,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACzC"}

package/dist/drivers/StoryRunner.js

@@ -0,0 +1 @@
+export {};

package/dist/drivers/codex-mcp/CodexMcpStoryRunner.d.ts

@@ -0,0 +1,25 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import type { ResolvedWorkflowConfig } from '../../types.js';
+import type { DriverToolStatus, StoryRunner, StoryRunRequest, StoryRunResult } from '../StoryRunner.js';
+type CodexMcpClient = Pick<Client, 'connect' | 'callTool' | 'listTools' | 'close'>;
+export interface CodexMcpStoryRunnerOptions {
+    startupTimeoutMs?: number;
+    requestTimeoutMs?: number;
+    retries?: number;
+    createClient?: () => {
+        client: CodexMcpClient;
+        transport: StdioClientTransport;
+    };
+}
+export declare class CodexMcpStoryRunner implements StoryRunner {
+    private readonly config;
+    private readonly options;
+    constructor(config: ResolvedWorkflowConfig, options?: CodexMcpStoryRunnerOptions);
+    runStory(request: StoryRunRequest): Promise<StoryRunResult>;
+    checkTools(): Promise<DriverToolStatus>;
+    private withClient;
+    private createClient;
+}
+export {};
+//# sourceMappingURL=CodexMcpStoryRunner.d.ts.map

package/dist/drivers/codex-mcp/CodexMcpStoryRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CodexMcpStoryRunner.d.ts","sourceRoot":"","sources":["../../../src/drivers/codex-mcp/CodexMcpStoryRunner.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AAKjF,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,WAAW,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AASxG,KAAK,cAAc,GAAG,IAAI,CAAC,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,WAAW,GAAG,OAAO,CAAC,CAAC;AAEnF,MAAM,WAAW,0BAA0B;IACzC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM;QAAE,MAAM,EAAE,cAAc,CAAC;QAAC,SAAS,EAAE,oBAAoB,CAAA;KAAE,CAAC;CAClF;AAED,qBAAa,mBAAoB,YAAW,WAAW;IAEnD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;gBADP,MAAM,EAAE,sBAAsB,EAC9B,OAAO,GAAE,0BAA+B;IAGrD,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAuC3D,UAAU,IAAI,OAAO,CAAC,gBAAgB,CAAC;YAsB/B,UAAU;IAwBxB,OAAO,CAAC,YAAY;CAcrB"}

package/dist/drivers/codex-mcp/CodexMcpStoryRunner.js

@@ -0,0 +1,145 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import pRetry, { AbortError } from 'p-retry';
+import pTimeout from 'p-timeout';
+import { isRecord } from '../../internal/guards.js';
+import { validateCodexToolSchemas } from './schemaValidation.js';
+import { buildCodexToolInput } from './toolInput.js';
+const VERSION = '0.1.0';
+const STARTUP_TIMEOUT_MS = 30_000;
+const REQUEST_TIMEOUT_MS = 60 * 60 * 1000;
+const RETRIES = 2;
+export class CodexMcpStoryRunner {
+    config;
+    options;
+    constructor(config, options = {}) {
+        this.config = config;
+        this.options = options;
+    }
+    async runStory(request) {
+        return await this.withClient(async (client) => {
+            const invocation = buildCodexToolInput(this.config, request.story, request.prompt);
+            const requestTimeoutMs = this.options.requestTimeoutMs ?? REQUEST_TIMEOUT_MS;
+            const totalTimeoutMs = Math.min(requestTimeoutMs, this.config.orchestrator.childTimeoutMs);
+            const rawResult = await pTimeout(client.callTool({
+                name: 'codex',
+                arguments: invocation,
+            }, undefined, {
+                timeout: requestTimeoutMs,
+                resetTimeoutOnProgress: true,
+                maxTotalTimeout: totalTimeoutMs,
+            }), {
+                milliseconds: totalTimeoutMs,
+                message: 'Codex MCP request timed out',
+            });
+            if (isToolError(rawResult)) {
+                throw new AbortError(extractContent(rawResult) || 'Codex MCP returned a tool error');
+            }
+            const output = validateCodexToolOutput(rawResult);
+            return {
+                storyId: request.story.id,
+                sessionId: output.threadId,
+                content: output.content,
+                rawResult,
+                invocation: invocation,
+            };
+        });
+    }
+    async checkTools() {
+        return await this.withClient(async (client) => {
+            const startupTimeoutMs = this.options.startupTimeoutMs ?? STARTUP_TIMEOUT_MS;
+            const result = await pTimeout(client.listTools({}, {
+                timeout: startupTimeoutMs,
+                maxTotalTimeout: startupTimeoutMs,
+            }), {
+                milliseconds: startupTimeoutMs,
+                message: 'Codex MCP tools/list timed out',
+            });
+            const tools = validateListToolsResult(result);
+            validateCodexToolSchemas(tools);
+            return { ok: true, tools: tools.map((tool) => tool.name) };
+        });
+    }
+    async withClient(operation) {
+        return await pRetry(async () => {
+            const { client, transport } = this.createClient();
+            try {
+                await pTimeout(client.connect(transport), {
+                    milliseconds: this.options.startupTimeoutMs ?? STARTUP_TIMEOUT_MS,
+                    message: 'Codex MCP startup timed out',
+                });
+                return await operation(client);
+            }
+            catch (error) {
+                if (error instanceof AbortError)
+                    throw error;
+                if (isTransientError(error))
+                    throw error;
+                throw new AbortError(error instanceof Error ? error : new Error(String(error)));
+            }
+            finally {
+                await client.close();
+            }
+        }, {
+            retries: this.options.retries ?? RETRIES,
+        });
+    }
+    createClient() {
+        if (this.options.createClient)
+            return this.options.createClient();
+        const client = new Client({
+            name: 'agentic-workflow-kit-orchestrator',
+            version: VERSION,
+        });
+        const transport = new StdioClientTransport({
+            command: 'codex',
+            args: ['mcp-server'],
+            cwd: this.config.workspace.rootAbs,
+            stderr: 'inherit',
+        });
+        return { client, transport };
+    }
+}
+function validateCodexToolOutput(value) {
+    if (!isRecord(value))
+        throw new AbortError('Codex MCP result must be an object');
+    if (!isRecord(value.structuredContent))
+        throw new AbortError('Codex MCP result missing structuredContent');
+    const { threadId, content } = value.structuredContent;
+    if (typeof threadId !== 'string' || threadId.length === 0) {
+        throw new AbortError('Codex MCP result missing structuredContent.threadId');
+    }
+    if (typeof content !== 'string') {
+        throw new AbortError('Codex MCP result missing structuredContent.content');
+    }
+    return { threadId, content };
+}
+function validateListToolsResult(value) {
+    if (!isRecord(value) || !Array.isArray(value.tools)) {
+        throw new AbortError('MCP tools/list result must contain a tools array');
+    }
+    return value.tools.map((tool, index) => {
+        if (!isRecord(tool) || typeof tool.name !== 'string' || !isRecord(tool.inputSchema)) {
+            throw new AbortError(`MCP tool ${index} is malformed`);
+        }
+        return tool;
+    });
+}
+function isToolError(value) {
+    return isRecord(value) && value.isError === true;
+}
+function extractContent(value) {
+    if (!isRecord(value) || !Array.isArray(value.content))
+        return '';
+    return value.content
+        .filter((block) => isRecord(block) && block.type === 'text' && typeof block.text === 'string')
+        .map((block) => block.text)
+        .join('\n');
+}
+function isTransientError(error) {
+    if (!(error instanceof Error))
+        return false;
+    // Retry only connect/startup transients. Request timeouts can represent a full story run,
+    // and ENOENT means the codex binary is missing, so both must fail without retry.
+    return /(startup|connect|connection|ECONN)/i.test(error.message);
+}

package/dist/drivers/codex-mcp/schemaValidation.d.ts

@@ -0,0 +1,7 @@
+export interface McpTool {
+    name: string;
+    inputSchema: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export declare function validateCodexToolSchemas(tools: McpTool[]): void;
+//# sourceMappingURL=schemaValidation.d.ts.map

package/dist/drivers/codex-mcp/schemaValidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemaValidation.d.ts","sourceRoot":"","sources":["../../../src/drivers/codex-mcp/schemaValidation.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAKD,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,CAoB/D"}

package/dist/drivers/codex-mcp/schemaValidation.js

@@ -0,0 +1,43 @@
+import { isRecord } from '../../internal/guards.js';
+const REQUIRED_APPROVAL_POLICIES = ['never', 'on-failure', 'on-request', 'untrusted'];
+const REQUIRED_SANDBOX_MODES = ['danger-full-access', 'read-only', 'workspace-write'];
+export function validateCodexToolSchemas(tools) {
+    const codex = tools.find((tool) => tool.name === 'codex');
+    if (!codex) {
+        throw new Error('Codex MCP server must expose a codex tool');
+    }
+    if (codex.inputSchema?.type !== 'object') {
+        throw new Error('Codex MCP codex tool must declare an object input schema');
+    }
+    const properties = codex.inputSchema.properties;
+    if (!isRecord(properties) || !isRecord(properties.prompt)) {
+        throw new Error('Codex MCP codex tool must declare a prompt input property');
+    }
+    requireProperty(properties, 'model');
+    requireProperty(properties, 'config');
+    const approvalPolicy = requireProperty(properties, 'approval-policy');
+    const sandbox = requireProperty(properties, 'sandbox');
+    validateEnumIfPresent(approvalPolicy, REQUIRED_APPROVAL_POLICIES, 'approval-policy');
+    validateEnumIfPresent(sandbox, REQUIRED_SANDBOX_MODES, 'sandbox');
+}
+function requireProperty(properties, propertyName) {
+    if (!(propertyName in properties)) {
+        const article = propertyName === 'approval-policy' ? 'an' : 'a';
+        throw new Error(`Codex MCP codex tool must declare ${article} ${propertyName} input property`);
+    }
+    return properties[propertyName];
+}
+function validateEnumIfPresent(schema, requiredValues, propertyName) {
+    if (!isRecord(schema) || schema.enum === undefined) {
+        return;
+    }
+    if (!Array.isArray(schema.enum)) {
+        throw new Error(`Codex MCP ${propertyName} input enum must be an array`);
+    }
+    const values = new Set(schema.enum);
+    for (const required of requiredValues) {
+        if (!values.has(required)) {
+            throw new Error(`Codex MCP ${propertyName} input enum must include "${required}"`);
+        }
+    }
+}

package/dist/drivers/codex-mcp/toolInput.d.ts

@@ -0,0 +1,12 @@
+import type { ResolvedGitConfig, ResolvedWorkflowConfig, WorkflowStory } from '../../types.js';
+export interface CodexToolInput {
+    cwd: string;
+    prompt: string;
+    config?: Record<string, unknown>;
+    model?: string;
+    'approval-policy'?: string;
+    sandbox?: string;
+}
+export declare function buildCodexToolInput(config: ResolvedWorkflowConfig, story: WorkflowStory, prompt?: string): CodexToolInput;
+export declare function buildGenericPrompt(story: WorkflowStory, git: ResolvedGitConfig): string;
+//# sourceMappingURL=toolInput.d.ts.map

package/dist/drivers/codex-mcp/toolInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolInput.d.ts","sourceRoot":"","sources":["../../../src/drivers/codex-mcp/toolInput.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/F,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,sBAAsB,EAC9B,KAAK,EAAE,aAAa,EACpB,MAAM,SAAwC,GAC7C,cAAc,CAkChB;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,iBAAiB,GAAG,MAAM,CAyCvF"}

package/dist/drivers/codex-mcp/toolInput.js

@@ -0,0 +1,82 @@
+import path from 'node:path';
+export function buildCodexToolInput(config, story, prompt = buildGenericPrompt(story, config.git)) {
+    const childSession = config.codex.childSession;
+    const input = {
+        cwd: childSession.cwdAbs,
+        prompt,
+    };
+    if (childSession.model)
+        input.model = childSession.model;
+    if (childSession.approvalPolicy)
+        input['approval-policy'] = childSession.approvalPolicy;
+    if (childSession.sandbox)
+        input.sandbox = childSession.sandbox;
+    // D8 fix: inject the workspace .git and .worktrees directories as codex writable roots so the
+    // child session can run `git commit` and `git worktree add` under --sandbox workspace-write.
+    // Under workspace-write codex makes .git read-only by default, which prevents any git commit
+    // (every commit updates a ref under .git/refs/heads). Granting these two paths as writable roots
+    // keeps workspace-write restrictions intact for everything else (network, system dirs) while
+    // allowing git isolation to work. This is harmless under danger-full-access (already writable)
+    // and read-only (the child would not be committing anyway).
+    //
+    // Config shape: sandbox_workspace_write is a top-level TOML table in codex config, so we
+    // represent it as a nested object { sandbox_workspace_write: { writable_roots: [...] } } — the
+    // same mechanism used for scalar keys like model_reasoning_effort, but one level deeper because
+    // sandbox_workspace_write is a table, not a bare key. Verified empirically on 2026-06-03 via
+    // `codex exec -c 'sandbox_workspace_write.writable_roots=[...]'` (see d8-dispatch-sandbox-plan.md).
+    const workspaceRoot = childSession.cwdAbs;
+    const gitAbs = path.join(workspaceRoot, '.git');
+    const worktreesAbs = path.join(workspaceRoot, '.worktrees');
+    const writableRootsEntry = {
+        sandbox_workspace_write: { writable_roots: [gitAbs, worktreesAbs] },
+    };
+    input.config = { ...childSession.config, ...writableRootsEntry };
+    return input;
+}
+export function buildGenericPrompt(story, git) {
+    const metadata = story.metadata;
+    const branchPattern = renderBranchPattern(story, git.branchPattern);
+    const commitOnBase = git.commitOnBase === 'forbid'
+        ? `Committing directly on \`${git.baseBranch}\` is forbidden.`
+        : `Committing directly on \`${git.baseBranch}\` is allowed by this repo policy.`;
+    return [
+        'Implement exactly one workflow tracker story from the current repository.',
+        '',
+        'Story:',
+        `- ID: ${story.id}`,
+        `- Title: ${story.title}`,
+        `- Status: ${story.status}`,
+        story.owner ? `- Owner: ${story.owner}` : '- Owner: unowned',
+        story.dependencies.length > 0 ? `- Dependencies: ${story.dependencies.join(', ')}` : '- Dependencies: none',
+        `- Track ID: ${metadata.trackId}`,
+        `- Track: ${metadata.trackTitle}`,
+        `- Tracker file: ${metadata.trackerPath}`,
+        metadata.wave ? `- Wave/phase: ${metadata.wave}` : null,
+        metadata.spec ? `- Spec: ${metadata.spec}` : null,
+        metadata.plan ? `- Plan: ${metadata.plan}` : null,
+        metadata.pr ? `- PR: ${metadata.pr}` : null,
+        '',
+        'Git policy (from .workflow/config.yaml - follow exactly):',
+        `- Isolation strategy: ${git.strategy}`,
+        `- Create/use branch: ${branchPattern} (base: ${git.baseBranch})`,
+        `- ${commitOnBase}`,
+        '- You MUST create the isolated branch/worktree, commit your work there, and confirm the commit exists BEFORE reporting the story done. An uncommitted tracker edit is not acceptance.',
+        '',
+        'Instructions:',
+        '1. Read repository instructions first, including AGENTS.md when present.',
+        '2. Read the selected tracker row and any linked spec, plan, related docs, or acceptance notes.',
+        '3. Implement only this story. Do not bundle adjacent tracker rows or unrelated cleanup.',
+        '4. Follow the Git policy above and the repository documentation, review, and verification rules.',
+        '5. Update the tracker row through the repository workflow when the story is complete.',
+        '6. The tracker row status is the only completion authority; child prose is not enough.',
+        '7. Report changed files, verification evidence, and blockers.',
+    ]
+        .filter((line) => line !== null)
+        .join('\n');
+}
+function renderBranchPattern(story, branchPattern) {
+    return branchPattern
+        .replaceAll('{track}', story.metadata.trackId)
+        .replaceAll('{id}', story.id)
+        .replaceAll('{id-lc}', story.id.toLowerCase());
+}

package/dist/git/GitInspector.d.ts

@@ -0,0 +1,34 @@
+import type { ResolvedGitConfig, WorkflowStory } from '../types.js';
+export interface StoryCommitEvidence {
+    committed: boolean;
+    branch: string | null;
+    isBaseBranch: boolean;
+    headSha: string | null;
+    baseSha: string | null;
+    uncommittedChanges: boolean;
+}
+export interface GitInspector {
+    snapshotBaseSha?(args: {
+        git: ResolvedGitConfig;
+        cwdAbs: string;
+    }): Promise<string | null>;
+    inspectStory(args: {
+        story: WorkflowStory;
+        git: ResolvedGitConfig;
+        cwdAbs: string;
+        baseShaAtLaunch?: string | null;
+    }): Promise<StoryCommitEvidence>;
+}
+export declare class RealGitInspector implements GitInspector {
+    snapshotBaseSha(args: {
+        git: ResolvedGitConfig;
+        cwdAbs: string;
+    }): Promise<string | null>;
+    inspectStory(args: {
+        story: WorkflowStory;
+        git: ResolvedGitConfig;
+        cwdAbs: string;
+        baseShaAtLaunch?: string | null;
+    }): Promise<StoryCommitEvidence>;
+}
+//# sourceMappingURL=GitInspector.d.ts.map

package/dist/git/GitInspector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GitInspector.d.ts","sourceRoot":"","sources":["../../src/git/GitInspector.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAIpE,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,YAAY,EAAE,OAAO,CAAC;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,kBAAkB,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,YAAY;IAC3B,eAAe,CAAC,CAAC,IAAI,EAAE;QAAE,GAAG,EAAE,iBAAiB,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC3F,YAAY,CAAC,IAAI,EAAE;QACjB,KAAK,EAAE,aAAa,CAAC;QACrB,GAAG,EAAE,iBAAiB,CAAC;QACvB,MAAM,EAAE,MAAM,CAAC;QACf,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACjC,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAClC;AAED,qBAAa,gBAAiB,YAAW,YAAY;IAC7C,eAAe,CAAC,IAAI,EAAE;QAAE,GAAG,EAAE,iBAAiB,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAIzF,YAAY,CAAC,IAAI,EAAE;QACvB,KAAK,EAAE,aAAa,CAAC;QACrB,GAAG,EAAE,iBAAiB,CAAC;QACvB,MAAM,EAAE,MAAM,CAAC;QACf,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACjC,GAAG,OAAO,CAAC,mBAAmB,CAAC;CA8BjC"}

package/dist/git/GitInspector.js

@@ -0,0 +1,73 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+export class RealGitInspector {
+    async snapshotBaseSha(args) {
+        return await maybeGitOutput(args.cwdAbs, ['rev-parse', '--verify', args.git.baseBranch]);
+    }
+    async inspectStory(args) {
+        const currentBranch = await gitOutput(args.cwdAbs, ['rev-parse', '--abbrev-ref', 'HEAD']);
+        const baseSha = await maybeGitOutput(args.cwdAbs, ['rev-parse', '--verify', args.git.baseBranch]);
+        const storyBranch = await resolveStoryBranch(args.cwdAbs, args.story, args.git);
+        const inspectedBranch = storyBranch ?? currentBranch;
+        const headSha = inspectedBranch
+            ? await maybeGitOutput(args.cwdAbs, ['rev-parse', '--verify', inspectedBranch])
+            : null;
+        // Only the resolved story branch determines base-branch placement. In worktree strategy the
+        // inspected root checkout stays on the base branch while the child commits on a sibling worktree's
+        // story branch, so the inspected checkout's own HEAD must not contaminate this judgement.
+        const isBaseBranch = inspectedBranch === args.git.baseBranch;
+        const uncommittedChanges = (await gitOutput(args.cwdAbs, ['status', '--porcelain'])).length > 0;
+        const comparisonBase = args.baseShaAtLaunch ?? baseSha;
+        const commitCount = inspectedBranch && comparisonBase
+            ? parseCommitCount(await maybeGitOutput(args.cwdAbs, ['rev-list', '--count', `${comparisonBase}..${inspectedBranch}`]))
+            : 0;
+        return {
+            committed: commitCount > 0,
+            branch: inspectedBranch,
+            isBaseBranch,
+            headSha,
+            baseSha,
+            uncommittedChanges,
+        };
+    }
+}
+async function resolveStoryBranch(cwdAbs, story, git) {
+    const pattern = branchSearchPattern(story, git);
+    const output = await gitOutput(cwdAbs, ['branch', '--list', pattern]);
+    const branches = output
+        .split('\n')
+        // Strip the current-branch marker (`* `) and the other-worktree marker (`+ `) that
+        // `git branch --list` prepends; an unstripped `+ ` corrupts the branch name passed to rev-list.
+        .map((line) => line.replace(/^[*+]\s*/, '').trim())
+        .filter(Boolean)
+        .sort();
+    // A retried story can leave >1 branch matching the {slug} glob. Pick deterministically
+    // (lexically-first) so completion evidence is stable across runs rather than order-dependent.
+    return branches[0] ?? null;
+}
+function branchSearchPattern(story, git) {
+    return git.branchPattern
+        .replaceAll('{track}', story.metadata.trackId)
+        .replaceAll('{id}', story.id)
+        .replaceAll('{id-lc}', story.id.toLowerCase())
+        .replaceAll('{slug}', '*');
+}
+function parseCommitCount(value) {
+    if (value === null)
+        return 0;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+async function gitOutput(cwd, args) {
+    const { stdout } = await execFileAsync('git', args, { cwd });
+    return stdout.trim();
+}
+async function maybeGitOutput(cwd, args) {
+    try {
+        return await gitOutput(cwd, args);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { analyzeWorkflowRun } from './analysis/runAnalyzer.js';
+export { createRunId, loadResolvedConfig } from './config/configLoader.js';
+export { buildConfigJsonSchema, serializeConfigJsonSchema } from './config/jsonSchema.js';
+export { type PresetName, type RepoSignals, selectPreset } from './config/preset.js';
+export { type LoadConfigOptions, type LoadedConfig, loadConfig } from './config/resolve.js';
+export { ConfigSchema, type WorkflowConfig } from './config/schema.js';
+export { WorkflowRunner } from './runner/WorkflowRunner.js';
+export { isCompleteStatus, selectDispatchableStories } from './scheduler/scheduler.js';
+export { discoverMarkdownTracks, parseTrackerStories } from './tracks/markdownTracker.js';
+export type { ResolvedWorkflowConfig, RunState, WorkflowCommand, WorkflowStory, WorkflowTrack, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAE,qBAAqB,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAC;AAC1F,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACrF,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,YAAY,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAC5F,OAAO,EAAE,YAAY,EAAE,KAAK,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACvE,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,yBAAyB,EAAE,MAAM,0BAA0B,CAAC;AACvF,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAC1F,YAAY,EACV,sBAAsB,EACtB,QAAQ,EACR,eAAe,EACf,aAAa,EACb,aAAa,GACd,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+export { analyzeWorkflowRun } from './analysis/runAnalyzer.js';
+export { createRunId, loadResolvedConfig } from './config/configLoader.js';
+export { buildConfigJsonSchema, serializeConfigJsonSchema } from './config/jsonSchema.js';
+export { selectPreset } from './config/preset.js';
+export { loadConfig } from './config/resolve.js';
+export { ConfigSchema } from './config/schema.js';
+export { WorkflowRunner } from './runner/WorkflowRunner.js';
+export { isCompleteStatus, selectDispatchableStories } from './scheduler/scheduler.js';
+export { discoverMarkdownTracks, parseTrackerStories } from './tracks/markdownTracker.js';

package/dist/internal/guards.d.ts

@@ -0,0 +1,4 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function isNodeError(value: unknown): value is NodeJS.ErrnoException;
+export declare function safeName(value: string): string;
+//# sourceMappingURL=guards.d.ts.map

package/dist/internal/guards.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../../src/internal/guards.ts"],"names":[],"mappings":"AAAA,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEzE;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,cAAc,CAE1E;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9C"}

package/dist/internal/guards.js

@@ -0,0 +1,9 @@
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function isNodeError(value) {
+    return value instanceof Error && 'code' in value;
+}
+export function safeName(value) {
+    return value.replace(/[^a-zA-Z0-9._-]+/g, '-');
+}

package/dist/logging/ConsoleLogger.d.ts

@@ -0,0 +1,7 @@
+import type { Logger } from '../types.js';
+export declare class ConsoleLogger implements Logger {
+    info(message: string, fields?: Record<string, unknown>): void;
+    warn(message: string, fields?: Record<string, unknown>): void;
+    error(message: string, fields?: Record<string, unknown>): void;
+}
+//# sourceMappingURL=ConsoleLogger.d.ts.map

package/dist/logging/ConsoleLogger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConsoleLogger.d.ts","sourceRoot":"","sources":["../../src/logging/ConsoleLogger.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,qBAAa,aAAc,YAAW,MAAM;IAC1C,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,IAAI;IAGjE,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,IAAI;IAGjE,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,IAAI;CAGnE"}

package/dist/logging/ConsoleLogger.js

@@ -0,0 +1,16 @@
+export class ConsoleLogger {
+    info(message, fields = {}) {
+        console.log(format('info', message, fields));
+    }
+    warn(message, fields = {}) {
+        console.warn(format('warn', message, fields));
+    }
+    error(message, fields = {}) {
+        console.error(format('error', message, fields));
+    }
+}
+function format(level, message, fields) {
+    return Object.keys(fields).length > 0
+        ? JSON.stringify({ level, message, ...fields })
+        : JSON.stringify({ level, message });
+}

package/dist/metrics/aggregate.d.ts

@@ -0,0 +1,6 @@
+import type { ChildMetricsSnapshot, LiveMetricsSnapshot, TokenTotals } from '../types.js';
+export declare function mergeChildMetrics(children: ChildMetricsSnapshot[]): LiveMetricsSnapshot['aggregate'];
+export declare function addTokenTotals(a: TokenTotals, b: TokenTotals): TokenTotals;
+export declare function mergeCounts(target: Record<string, number>, source: Record<string, number>): void;
+export declare function emptyTokenTotals(): TokenTotals;
+//# sourceMappingURL=aggregate.d.ts.map

package/dist/metrics/aggregate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate.d.ts","sourceRoot":"","sources":["../../src/metrics/aggregate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1F,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,oBAAoB,EAAE,GAAG,mBAAmB,CAAC,WAAW,CAAC,CAgBpG;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,EAAE,WAAW,GAAG,WAAW,CAQ1E;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAIhG;AAED,wBAAgB,gBAAgB,IAAI,WAAW,CAE9C"}