praxis-agent 0.60.0 → 0.60.1

package/README.md

@@ -102,6 +102,7 @@ Common non-interactive operations:
 
 ```sh
 praxis -p "Inspect this project"
+printf 'Inspect this project\n' | praxis -p
 praxis -p --output-format json "Summarize the test failures"
 praxis --resume
 praxis sessions --json
@@ -213,7 +214,9 @@ troubleshooting. Run `praxis --help` for the authoritative command surface.
   Claude-compatible main-thread agent definitions with native prompt, model,
   tool, memory, first-turn, and resume behavior. Agent execution uses one
   durable lifecycle vocabulary with bounded cancellation and drain,
-  continuation, notifications, and single-owner orphan recovery. Experimental
+  continuation, notifications, and single-owner orphan recovery. Isolated
+  Workflow turns use ownership-recorded repo-local temporary worktrees and
+  retain dirty or committed results for inspection. Experimental
   local Teams (`PRAXIS_ENABLE_TEAMS=true`) stay absent from ordinary startup by
   default and add durable task ownership plus one ordered mailbox with stable
   identities, fixed broadcast recipients, durable cursors, bounded retention,

package/dist/application/managed-worktree.d.ts

@@ -6,6 +6,16 @@ export interface ManagedWorktree {
     cwd: string;
     cleanup(): Promise<ManagedWorktreeCleanup>;
 }
+export interface OwnedManagedWorktreeOptions {
+    cwd: string;
+    stateRoot: string;
+    directoryName: string;
+    ownerId: string;
+    label: 'Agent' | 'Workflow' | 'Team';
+    kind: 'workflow' | 'agent' | 'team';
+    policy: 'ephemeral' | 'durable';
+}
+export declare function createOwnedManagedWorktree(options: OwnedManagedWorktreeOptions): Promise<ManagedWorktree>;
 export declare function createManagedWorktree(options: {
     cwd: string;
     parentDirectory: string;

package/dist/application/managed-worktree.js

@@ -1,17 +1,567 @@
 import { execFile } from 'node:child_process';
-import { lstat, mkdir, realpath } from 'node:fs/promises';
-import { isAbsolute, join, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, realpath } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
 import { promisify } from 'node:util';
+import { ManagedWorktreeStore, } from '../persistence/managed-worktree-store.js';
+import { resolveProjectIdentity } from '../platform/project-identity.js';
+import { writeFileAtomically } from '../platform/atomic-write.js';
+import { ExclusiveFileLease, } from '../platform/exclusive-file-lease.js';
 const execFileAsync = promisify(execFile);
+async function gitRaw(cwd, args) {
+    return (await execFileAsync('git', ['-C', cwd, ...args], { encoding: 'utf8' })).stdout;
+}
 async function git(cwd, args) {
-    return (await execFileAsync('git', ['-C', cwd, ...args], { encoding: 'utf8' })).stdout.trim();
+    return (await gitRaw(cwd, args)).trim();
+}
+async function gitOptional(cwd, args) {
+    try {
+        return await git(cwd, args);
+    }
+    catch (error) {
+        if (error.code === 1)
+            return null;
+        throw error;
+    }
 }
 async function registeredWorktrees(root) {
-    const output = await git(root, ['worktree', 'list', '--porcelain']);
+    const output = await gitRaw(root, ['worktree', 'list', '--porcelain', '-z']);
     return new Set(output
-        .split('\n')
+        .split('\0')
         .filter((line) => line.startsWith('worktree '))
-        .map((line) => resolve(line.slice('worktree '.length))));
+        .map((line) => resolve(root, line.slice('worktree '.length))));
+}
+const COMPONENT_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,191}$/u;
+const MARKER_FIELDS = new Set(['version', 'worktreeId', 'repositoryRoot']);
+const LOCAL_EXCLUDE_PATTERN = '/.praxis/worktrees/';
+function managedWorktreeId(repositoryRoot, kind, ownerId) {
+    return createHash('sha256')
+        .update(`${repositoryRoot}\0${kind}\0${ownerId}`)
+        .digest('hex');
+}
+function validOwnerId(ownerId) {
+    return (ownerId.length > 0 &&
+        ownerId.length <= 256 &&
+        !Array.from(ownerId).some((character) => {
+            const code = character.codePointAt(0) ?? 0;
+            return code <= 0x1f || code === 0x7f;
+        }));
+}
+function worktreeError(options, message) {
+    return new Error(`${options.label} worktree ${message}`);
+}
+async function assertRealDirectory(path, description) {
+    let current = resolve(path);
+    const parts = [];
+    while (true) {
+        parts.unshift(current);
+        const parent = resolve(current, '..');
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    for (const part of parts) {
+        try {
+            const entry = await lstat(part);
+            if (entry.isSymbolicLink())
+                throw new Error(`${description} must not be a symlink`);
+            if (!entry.isDirectory())
+                throw new Error(`${description} must be a directory`);
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                continue;
+            throw error;
+        }
+    }
+}
+async function acquireLease(lease, description) {
+    for (let attempt = 0; attempt < 400; attempt += 1) {
+        const handle = await lease.tryAcquire();
+        if (handle)
+            return handle;
+        await sleep(5);
+    }
+    throw new Error(`Timed out acquiring ${description}`);
+}
+async function readRegularFile(path, description) {
+    let handle;
+    try {
+        handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (error.code === 'ELOOP') {
+            throw new Error(`${description} must be a regular file`);
+        }
+        throw error;
+    }
+    try {
+        if (!(await handle.stat()).isFile()) {
+            throw new Error(`${description} must be a regular file`);
+        }
+        return await handle.readFile({ encoding: 'utf8' });
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function ensureManagedRootIgnored(repositoryRoot) {
+    const commonValue = await git(repositoryRoot, [
+        'rev-parse',
+        '--git-common-dir',
+    ]);
+    const commonDirectory = await realpath(isAbsolute(commonValue)
+        ? commonValue
+        : resolve(repositoryRoot, commonValue));
+    const infoDirectory = join(commonDirectory, 'info');
+    await assertRealDirectory(commonDirectory, 'Git common directory');
+    await assertRealDirectory(infoDirectory, 'Git info directory');
+    await mkdir(infoDirectory, { recursive: true, mode: 0o700 });
+    await assertRealDirectory(infoDirectory, 'Git info directory');
+    const excludePath = join(infoDirectory, 'exclude');
+    const lease = await acquireLease(new ExclusiveFileLease(`${excludePath}.praxis.lock`), 'managed worktree ignore lock');
+    try {
+        let source = '';
+        try {
+            source = await readRegularFile(excludePath, 'Git info exclude');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const lines = source.split(/\r?\n/u);
+        if (lines.includes(LOCAL_EXCLUDE_PATTERN))
+            return;
+        const prefix = source.length > 0 && !source.endsWith('\n') ? '\n' : '';
+        const next = `${source}${prefix}${LOCAL_EXCLUDE_PATTERN}\n`;
+        const committed = await writeFileAtomically(excludePath, next, {
+            mode: 0o600,
+            beforeCommit: async () => {
+                try {
+                    return ((await readRegularFile(excludePath, 'Git info exclude')) === source);
+                }
+                catch (error) {
+                    return error.code === 'ENOENT' && !source;
+                }
+            },
+        });
+        if (!committed) {
+            throw new Error('Git info exclude changed during managed worktree setup');
+        }
+    }
+    finally {
+        await lease.release();
+    }
+}
+async function linkedGitDirectory(worktreePath) {
+    const value = await git(worktreePath, ['rev-parse', '--git-dir']);
+    return realpath(isAbsolute(value) ? value : resolve(worktreePath, value));
+}
+async function writeMarker(path, record) {
+    const gitDirectory = await linkedGitDirectory(path);
+    const marker = join(gitDirectory, 'PRAXIS_WORKTREE');
+    try {
+        await lstat(marker);
+        throw new Error('Managed worktree marker already exists');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const committed = await writeFileAtomically(marker, `${JSON.stringify({ version: 1, worktreeId: record.worktreeId, repositoryRoot: record.repositoryRoot })}\n`, {
+        mode: 0o600,
+        beforeCommit: async () => {
+            try {
+                await lstat(marker);
+                return false;
+            }
+            catch (error) {
+                return error.code === 'ENOENT';
+            }
+        },
+    });
+    if (!committed)
+        throw new Error('Managed worktree marker already exists');
+}
+async function readMarker(worktreePath, record) {
+    const markerPath = join(await linkedGitDirectory(worktreePath), 'PRAXIS_WORKTREE');
+    let marker;
+    try {
+        marker = JSON.parse(await readRegularFile(markerPath, 'worktree marker'));
+    }
+    catch {
+        throw new Error('worktree marker is invalid');
+    }
+    if (typeof marker !== 'object' ||
+        marker === null ||
+        Array.isArray(marker) ||
+        Object.keys(marker).length !== MARKER_FIELDS.size ||
+        Object.keys(marker).some((key) => !MARKER_FIELDS.has(key)) ||
+        marker.version !== 1 ||
+        marker.worktreeId !== record.worktreeId ||
+        marker.repositoryRoot !== record.repositoryRoot) {
+        throw new Error('worktree marker does not match ownership record');
+    }
+}
+async function inspectOwnedCheckout(record, registered) {
+    const registrations = registered ?? (await registeredWorktrees(record.repositoryRoot));
+    const pathEntry = await lstat(record.worktreePath);
+    if (pathEntry.isSymbolicLink() || !pathEntry.isDirectory()) {
+        throw new Error('worktree path is not a real directory');
+    }
+    await assertRealDirectory(record.worktreePath, 'managed worktree path');
+    if ((await realpath(record.worktreePath)) !== resolve(record.worktreePath)) {
+        throw new Error('worktree path is not canonical');
+    }
+    if (!registrations.has(resolve(record.worktreePath))) {
+        throw new Error('worktree is not registered');
+    }
+    const [status, head, topLevel] = await Promise.all([
+        git(record.worktreePath, ['status', '--porcelain']),
+        git(record.worktreePath, ['rev-parse', 'HEAD']),
+        git(record.worktreePath, ['rev-parse', '--show-toplevel']),
+    ]);
+    const worktreeRoot = await realpath(resolve(record.worktreePath, topLevel));
+    if (worktreeRoot !== resolve(record.worktreePath)) {
+        throw new Error('registered worktree root does not match');
+    }
+    const root = await resolveProjectIdentity(record.worktreePath);
+    if (root !== record.repositoryRoot) {
+        throw new Error('repository identity does not match');
+    }
+    await readMarker(record.worktreePath, record);
+    const branch = await gitOptional(record.worktreePath, [
+        'symbolic-ref',
+        '--quiet',
+        '--short',
+        'HEAD',
+    ]);
+    if (branch)
+        throw new Error('worktree is not detached');
+    return { status, head };
+}
+function sameOwnership(left, right) {
+    return (left.worktreeId === right.worktreeId &&
+        left.kind === right.kind &&
+        left.policy === right.policy &&
+        left.ownerId === right.ownerId &&
+        left.repositoryRoot === right.repositoryRoot &&
+        left.worktreePath === right.worktreePath &&
+        left.branch === right.branch &&
+        left.baseCommit === right.baseCommit &&
+        left.createdAt === right.createdAt);
+}
+function nextRecord(record, state, retentionReason) {
+    const base = { ...record };
+    delete base.retentionReason;
+    return {
+        ...base,
+        state,
+        updatedAt: new Date().toISOString(),
+        ...(retentionReason === undefined ? {} : { retentionReason }),
+    };
+}
+async function retain(store, record, reason) {
+    try {
+        await store.update(nextRecord(record, 'retained', reason));
+        return { retained: true, reason };
+    }
+    catch (error) {
+        return {
+            retained: true,
+            reason: `${reason}; could not persist retention state: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+export async function createOwnedManagedWorktree(options) {
+    if (!COMPONENT_PATTERN.test(options.directoryName)) {
+        throw worktreeError(options, 'name is invalid');
+    }
+    if (!validOwnerId(options.ownerId)) {
+        throw worktreeError(options, 'owner ID is invalid');
+    }
+    if (!['workflow', 'agent', 'team'].includes(options.kind)) {
+        throw worktreeError(options, 'kind is invalid');
+    }
+    let repositoryRoot;
+    let baseCommit;
+    try {
+        ;
+        [repositoryRoot, baseCommit] = await Promise.all([
+            resolveProjectIdentity(options.cwd),
+            git(options.cwd, ['rev-parse', 'HEAD']),
+        ]);
+    }
+    catch {
+        throw worktreeError(options, 'isolation requires a Git repository');
+    }
+    const kindRoot = join(repositoryRoot, '.praxis', 'worktrees', options.kind);
+    const worktreePath = join(kindRoot, options.directoryName);
+    const rootRelative = relative(kindRoot, worktreePath);
+    if (!rootRelative ||
+        rootRelative === '..' ||
+        rootRelative.startsWith(`..${sep}`) ||
+        isAbsolute(rootRelative)) {
+        throw worktreeError(options, 'path escapes its kind root');
+    }
+    await assertRealDirectory(join(repositoryRoot, '.praxis'), 'managed worktree parent');
+    await assertRealDirectory(join(repositoryRoot, '.praxis', 'worktrees'), 'managed worktree parent');
+    await assertRealDirectory(kindRoot, 'managed worktree kind root');
+    await ensureManagedRootIgnored(repositoryRoot);
+    const worktreeId = managedWorktreeId(repositoryRoot, options.kind, options.ownerId);
+    const store = new ManagedWorktreeStore(options.stateRoot, repositoryRoot, worktreeId);
+    const lease = await store.acquireLease();
+    if (!lease)
+        throw worktreeError(options, `is already owned: ${worktreePath}`);
+    const now = new Date().toISOString();
+    const record = {
+        version: 1,
+        worktreeId,
+        kind: options.kind,
+        policy: options.policy,
+        ownerId: options.ownerId,
+        repositoryRoot,
+        worktreePath,
+        branch: null,
+        baseCommit,
+        state: 'creating',
+        createdAt: now,
+        updatedAt: now,
+    };
+    let recordCreated = false;
+    let gitCreated = false;
+    let markerCreated = false;
+    let created = false;
+    try {
+        await store.create(record);
+        recordCreated = true;
+        try {
+            const entry = await lstat(worktreePath);
+            if (entry.isSymbolicLink()) {
+                throw worktreeError(options, 'path must not be a symlink');
+            }
+            throw worktreeError(options, `path already exists: ${worktreePath}`);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        await mkdir(kindRoot, { recursive: true });
+        await assertRealDirectory(kindRoot, 'managed worktree kind root');
+        await git(repositoryRoot, [
+            'worktree',
+            'add',
+            '--detach',
+            worktreePath,
+            baseCommit,
+        ]);
+        gitCreated = true;
+        await writeMarker(worktreePath, record);
+        markerCreated = true;
+        await store.update(nextRecord(record, 'active'));
+        created = true;
+    }
+    catch (error) {
+        let rollbackError;
+        let uncertainArtifact = false;
+        if (gitCreated) {
+            try {
+                if (!markerCreated) {
+                    throw new Error('ownership marker was not published');
+                }
+                const inspection = await inspectOwnedCheckout(record);
+                if (inspection.status.length > 0) {
+                    throw new Error('created worktree is no longer clean');
+                }
+                if (inspection.head !== record.baseCommit) {
+                    throw new Error('created worktree HEAD no longer matches its base');
+                }
+                await git(repositoryRoot, ['worktree', 'remove', worktreePath]);
+            }
+            catch (removeError) {
+                rollbackError = removeError;
+            }
+        }
+        else {
+            try {
+                const registered = await registeredWorktrees(repositoryRoot);
+                const pathExists = await lstat(worktreePath)
+                    .then(() => true)
+                    .catch((pathError) => {
+                    if (pathError.code === 'ENOENT') {
+                        return false;
+                    }
+                    throw pathError;
+                });
+                uncertainArtifact = pathExists || registered.has(resolve(worktreePath));
+            }
+            catch {
+                uncertainArtifact = true;
+            }
+        }
+        if (recordCreated) {
+            try {
+                const retentionReason = rollbackError
+                    ? `Could not roll back ${worktreePath}: ${rollbackError.message}`
+                    : uncertainArtifact
+                        ? `Creation failed with an unverified artifact at ${worktreePath}`
+                        : undefined;
+                const failed = retentionReason
+                    ? nextRecord(record, 'retained', retentionReason)
+                    : nextRecord(record, 'released');
+                await store.update(failed);
+            }
+            catch (stateError) {
+                rollbackError ??= stateError;
+            }
+        }
+        const primary = error instanceof Error ? error.message : String(error);
+        throw worktreeError(options, `could not be created: ${primary}${rollbackError ? `; cleanup warning: ${rollbackError.message}` : ''}`);
+    }
+    finally {
+        if (!created)
+            await lease.release();
+    }
+    let executionLease = lease;
+    let removedResult;
+    let cleanupInFlight;
+    return {
+        cwd: worktreePath,
+        cleanup: async () => {
+            if (removedResult)
+                return removedResult;
+            if (cleanupInFlight)
+                return cleanupInFlight;
+            const heldLease = executionLease;
+            executionLease = undefined;
+            cleanupInFlight = cleanupOwnedManagedWorktree(store, options, record, heldLease);
+            try {
+                const result = await cleanupInFlight;
+                if (!result.retained)
+                    removedResult = result;
+                return result;
+            }
+            finally {
+                cleanupInFlight = undefined;
+            }
+        },
+    };
+}
+async function cleanupOwnedManagedWorktree(store, options, original, heldLease) {
+    const lease = heldLease ?? (await store.acquireLease());
+    if (!lease)
+        return {
+            retained: true,
+            reason: `${options.label} worktree cleanup is already in progress`,
+        };
+    try {
+        let record;
+        try {
+            record = await store.read();
+        }
+        catch (error) {
+            return {
+                retained: true,
+                reason: `Could not inspect ${options.label.toLowerCase()} worktree record: ${error.message}`,
+            };
+        }
+        if (!sameOwnership(record, original)) {
+            return {
+                retained: true,
+                reason: `${options.label} worktree ownership record does not match`,
+            };
+        }
+        if (record.state === 'released')
+            return { retained: false };
+        if (record.state !== 'active' &&
+            record.state !== 'retained' &&
+            record.state !== 'releasing') {
+            return {
+                retained: true,
+                reason: `${options.label} worktree is not releasable`,
+            };
+        }
+        if (record.policy === 'durable') {
+            return retain(store, record, `${options.label} worktree uses durable retention policy`);
+        }
+        const releasing = nextRecord(record, 'releasing');
+        try {
+            await store.update(releasing);
+        }
+        catch (error) {
+            return {
+                retained: true,
+                reason: `Could not update ${options.label.toLowerCase()} worktree record: ${error.message}`,
+            };
+        }
+        const registered = await registeredWorktrees(record.repositoryRoot).catch(() => null);
+        if (!registered) {
+            return retain(store, releasing, `Could not inspect registered ${options.label.toLowerCase()} worktrees`);
+        }
+        try {
+            await lstat(record.worktreePath);
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                return retain(store, releasing, `Could not inspect ${options.label.toLowerCase()} worktree path: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            if (registered.has(resolve(record.worktreePath))) {
+                return retain(store, releasing, `${options.label} worktree is missing but remains registered at ${record.worktreePath}`);
+            }
+            try {
+                await store.update(nextRecord(releasing, 'released'));
+                return { retained: false };
+            }
+            catch (stateError) {
+                return {
+                    retained: false,
+                    reason: `${options.label} worktree is already absent but release state could not be persisted: ${stateError instanceof Error ? stateError.message : String(stateError)}`,
+                };
+            }
+        }
+        let inspection;
+        try {
+            inspection = await inspectOwnedCheckout(record, registered);
+        }
+        catch (error) {
+            const reason = `Could not verify ${options.label.toLowerCase()} worktree ${record.worktreePath}: ${error.message}`;
+            return retain(store, releasing, reason);
+        }
+        if (inspection.status.length > 0) {
+            const reason = `${options.label} worktree has uncommitted changes and was retained at ${record.worktreePath}`;
+            return retain(store, releasing, reason);
+        }
+        if (inspection.head !== record.baseCommit) {
+            const reason = `${options.label} worktree has commits and was retained at ${record.worktreePath}`;
+            return retain(store, releasing, reason);
+        }
+        try {
+            await git(record.repositoryRoot, [
+                'worktree',
+                'remove',
+                record.worktreePath,
+            ]);
+        }
+        catch (error) {
+            const reason = `Could not remove ${options.label.toLowerCase()} worktree ${record.worktreePath}: ${error.message}`;
+            return retain(store, releasing, reason);
+        }
+        try {
+            await store.update(nextRecord(releasing, 'released'));
+        }
+        catch (error) {
+            return {
+                retained: false,
+                reason: `Could not update ${options.label.toLowerCase()} worktree record after removal: ${error.message}`,
+            };
+        }
+        return { retained: false };
+    }
+    finally {
+        await lease.release();
+    }
 }
 export async function createManagedWorktree(options) {
     if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,191}$/u.test(options.directoryName)) {

package/dist/application/workflow-worktree.js

@@ -1,11 +1,13 @@
-import { join } from 'node:path';
-import { createManagedWorktree, } from './managed-worktree.js';
+import { createOwnedManagedWorktree, } from './managed-worktree.js';
 export async function createWorkflowWorktree(options) {
-    return createManagedWorktree({
+    return createOwnedManagedWorktree({
         cwd: options.cwd,
-        parentDirectory: join(options.praxisRoot, 'workflow-worktrees'),
+        stateRoot: options.praxisRoot,
         directoryName: `${options.runId}-${options.agentId}`,
+        ownerId: `workflow:${options.runId}:${options.agentId}`,
         label: 'Workflow',
+        kind: 'workflow',
+        policy: 'ephemeral',
     });
 }
 //# sourceMappingURL=workflow-worktree.js.map

package/dist/cli/protocol.d.ts

@@ -243,6 +243,7 @@ export interface ProtocolTimingProjection {
 }
 export declare function projectProtocolTimings(startedAt: number, requestAt?: number, outputAt?: number): ProtocolTimingProjection;
 export declare function createSuccessResult(result: ProtocolResult, info: CliRuntimeInfo, startedAt: number, modelTurns: number, context?: ProtocolSuccessProjectionContext): Record<string, unknown>;
+export declare function formatPrintTextError(message: string, context?: ProtocolErrorProjectionContext): string;
 export declare function createErrorResult(message: string, sessionId: string, startedAt: number, modelTurns: number, context?: ProtocolErrorProjectionContext): Record<string, unknown>;
 /**
  * Returns the argument text of a headless `/color` prompt, or undefined when

package/dist/cli/protocol.js

@@ -94,14 +94,44 @@ export function createSuccessResult(result, info, startedAt, modelTurns, context
         uuid: randomUUID(),
     };
 }
+function classifyErrorResult(message) {
+    const maxBudget = /Maximum budget of \$([0-9]+(?:\.[0-9]+)?) exceeded/iu.exec(message);
+    if (maxBudget || /maximum budget|budget .* exceeded/iu.test(message)) {
+        return {
+            subtype: 'error_max_budget_usd',
+            ...(maxBudget?.[1] === undefined ? {} : { maxBudgetUsd: maxBudget[1] }),
+        };
+    }
+    const maxTurns = /Maximum model turns of (\d+) exceeded/iu.exec(message);
+    if (maxTurns || /maximum model turns|model turn limit/iu.test(message)) {
+        return {
+            subtype: 'error_max_turns',
+            ...(maxTurns?.[1] === undefined ? {} : { maxTurns: maxTurns[1] }),
+        };
+    }
+    if (/StructuredOutput/iu.test(message)) {
+        return { subtype: 'error_max_structured_output_retries' };
+    }
+    return { subtype: 'error_during_execution' };
+}
 function errorResultSubtype(message) {
-    if (/maximum budget|budget .* exceeded/iu.test(message))
-        return 'error_max_budget_usd';
-    if (/maximum model turns|model turn limit/iu.test(message))
-        return 'error_max_turns';
-    if (/StructuredOutput/iu.test(message))
-        return 'error_max_structured_output_retries';
-    return 'error_during_execution';
+    return classifyErrorResult(message).subtype;
+}
+export function formatPrintTextError(message, context = {}) {
+    if (context.providerApiError === true) {
+        const normalized = typeof context.apiErrorStatus === 'number'
+            ? normalizeApiError(message, context.apiErrorStatus)
+            : message;
+        return `${normalized}\n`;
+    }
+    const classification = classifyErrorResult(message);
+    if (classification.maxTurns !== undefined)
+        return `Error: Reached max turns (${classification.maxTurns})`;
+    if (classification.maxBudgetUsd !== undefined)
+        return `Error: Exceeded USD budget (${classification.maxBudgetUsd})`;
+    if (classification.subtype === 'error_max_structured_output_retries')
+        return 'Error: Failed to provide valid structured output after maximum retries';
+    return 'Execution error';
 }
 export function createErrorResult(message, sessionId, startedAt, modelTurns, context = {}) {
     const duration = Date.now() - startedAt;

package/dist/cli-runtime.d.ts

@@ -34,6 +34,7 @@ export interface CliIO {
     stdout(message: string | Uint8Array): void;
     stderr(message: string): void;
     isTTY?: boolean;
+    stdinIsTTY?: boolean;
     readStdinLines?: () => AsyncIterable<string | Uint8Array>;
     readSecret?: (prompt: string, signal?: AbortSignal) => Promise<string>;
 }

package/dist/cli-runtime.js

@@ -65,7 +65,7 @@ import { WorkspaceContext } from './application/session-worktree.js';
 import { launchTmuxWorktree } from './platform/tmux-worktree.js';
 import { claudeSandboxRuntime } from './sandbox/claude-sandbox-runtime.js';
 import { nativeSandboxTempDirectory, loadClaudeSandboxSettings, } from './sandbox/claude-sandbox-settings.js';
-import { createErrorResult, createSuccessResult, isHeadlessCostCommand, matchHeadlessColorCommand, parseCliInvocation, projectProtocolTimings, readStreamJsonMessages, StreamJsonOutput, } from './cli/protocol.js';
+import { createErrorResult, createSuccessResult, isHeadlessCostCommand, matchHeadlessColorCommand, formatPrintTextError, parseCliInvocation, projectProtocolTimings, readStreamJsonMessages, StreamJsonOutput, } from './cli/protocol.js';
 import { isDirectProcessSigint } from './cli/process-signal.js';
 import { executeProviderAuthCommand } from './cli/provider-auth-command.js';
 import { describeClaudePlugin, initClaudePlugin, installClaudePlugin, loadClaudePlugins, readPluginRegistry, setClaudePluginEnabled, uninstallClaudePlugin, updateClaudePlugin, validateClaudePlugin, } from './plugins/claude-plugin-runtime.js';
@@ -893,6 +893,7 @@ const consoleIO = {
     stdout: (message) => process.stdout.write(message),
     stderr: (message) => process.stderr.write(message),
     isTTY: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    stdinIsTTY: Boolean(process.stdin.isTTY),
     readStdinLines: () => process.stdin,
     readSecret: readConsoleSecret,
 };
@@ -4243,7 +4244,7 @@ async function executeMcpCommand(args, invocation, io, dependencies, signal) {
     }
     throw new Error(`Unknown mcp command: ${action}`);
 }
-function eventSink(io, outputFormat, legacyJson = false) {
+function eventSink(io, outputFormat, legacyJson = false, printText = false) {
     const sensitiveValues = sensitiveEnvironmentValues(process.env);
     if (legacyJson) {
         return (event) => {
@@ -4261,6 +4262,12 @@ function eventSink(io, outputFormat, legacyJson = false) {
     }
     if (outputFormat !== 'text')
         return () => undefined;
+    if (printText)
+        return (event) => {
+            if (event.type === 'warning') {
+                io.stderr(`Warning: ${redactSensitiveText(event.message, sensitiveValues)}\n`);
+            }
+        };
     let turnBuffered = false;
     let bufferedText = '';
     const flushBufferedText = () => {
@@ -4313,6 +4320,29 @@ function promptFrom(values) {
         throw new Error('Prompt is required');
     return prompt;
 }
+async function resolvePrintTextPrompt(io, argvPrompt) {
+    const missingInput = () => new Error('Error: Input must be provided either through stdin or as a prompt argument when using --print');
+    if (io.stdinIsTTY !== false) {
+        if (argvPrompt !== undefined)
+            return argvPrompt;
+        throw missingInput();
+    }
+    const input = io.readStdinLines?.();
+    if (!input)
+        throw new Error('print text input requires stdin support');
+    const chunks = [];
+    for await (const chunk of input) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    const stdinText = Buffer.concat(chunks).toString('utf8');
+    if (argvPrompt !== undefined && stdinText.length > 0)
+        return `${argvPrompt}\n${stdinText}`;
+    if (argvPrompt !== undefined)
+        return argvPrompt;
+    if (stdinText.length > 0)
+        return stdinText;
+    throw missingInput();
+}
 function backgroundWorkerArgv(argv) {
     const filtered = [];
     let optionsEnded = false;
@@ -5578,9 +5608,14 @@ async function execute(argv, io, dependencies, signal) {
         };
     };
     const headlessPromptArgs = command === 'resume' ? args.slice(2) : knownCommand ? args.slice(1) : args;
-    const headlessPrompt = inputFormat === 'text' && headlessPromptArgs.length > 0
+    const headlessTurnReached = invocation.rewindFiles === undefined &&
+        !['sessions', 'fork', 'inspect', 'export'].includes(command ?? 'run');
+    const argvHeadlessPrompt = inputFormat === 'text' && headlessPromptArgs.length > 0
         ? promptFrom(headlessPromptArgs)
         : undefined;
+    const headlessPrompt = inputFormat === 'text' && headlessTurnReached && invocation.print
+        ? await resolvePrintTextPrompt(io, argvHeadlessPrompt)
+        : argvHeadlessPrompt;
     if (headlessPrompt === '/release-notes' && !invocation.disableSlashCommands) {
         const startedAt = Date.now();
         const sessionId = invocation.sessionId ?? randomUUID();
@@ -5629,8 +5664,6 @@ async function execute(argv, io, dependencies, signal) {
         }
         return 0;
     }
-    const headlessTurnReached = invocation.rewindFiles === undefined &&
-        !['sessions', 'fork', 'inspect', 'export'].includes(command ?? 'run');
     if (streamIterator && headlessTurnReached) {
         const first = await nextStreamUser();
         if (first)
@@ -5686,7 +5719,7 @@ async function execute(argv, io, dependencies, signal) {
                         io.stderr(`Warning: ${redactSensitiveText(event.message, sensitiveEnvironmentValues(process.env))}\n`);
                     }
                 }
-                : eventSink(io, outputFormat, invocation.legacyJson),
+                : eventSink(io, outputFormat, invocation.legacyJson, invocation.print && inputFormat === 'text'),
         requireProvider: !streamInputExhausted &&
             !firstTurnIsLocalColor &&
             !firstTurnIsLocalCost &&
@@ -5818,6 +5851,7 @@ async function execute(argv, io, dependencies, signal) {
         if (streamInputExhausted)
             return 0;
         const initialPrompt = firstStreamMessage?.prompt ??
+            headlessPrompt ??
             promptFrom(command === 'resume'
                 ? args.slice(2)
                 : knownCommand
@@ -5833,7 +5867,6 @@ async function execute(argv, io, dependencies, signal) {
             signal?.addEventListener('abort', forwardAbort, { once: true });
             currentTurnAbort = streamIterator ? turnAbort : undefined;
             const runSignal = streamIterator ? turnAbort.signal : signal;
-            await ensureCostBaseline(activeSessionId);
             jsonModelTurns = 0;
             jsonRequestAt = undefined;
             jsonOutputAt = undefined;
@@ -5851,6 +5884,7 @@ async function execute(argv, io, dependencies, signal) {
             let colorArgs;
             let costTurn = false;
             try {
+                await ensureCostBaseline(activeSessionId);
                 costTurn =
                     !invocation.disableSlashCommands && isHeadlessCostCommand(prompt);
                 colorArgs = invocation.disableSlashCommands
@@ -5939,6 +5973,11 @@ async function execute(argv, io, dependencies, signal) {
                 else if (outputFormat === 'json') {
                     writeJson(io, createErrorResult(message, activeSessionId, startedAt, jsonModelTurns, errorContext));
                 }
+                else if (invocation.print &&
+                    inputFormat === 'text' &&
+                    outputFormat === 'text') {
+                    io.stdout(formatPrintTextError(message, errorContext));
+                }
                 else {
                     if (currentTurnAbort === turnAbort)
                         currentTurnAbort = undefined;
@@ -5971,6 +6010,8 @@ async function execute(argv, io, dependencies, signal) {
             }
             else if (outputFormat !== 'text')
                 writeJson(io, { type: 'result', ...result });
+            else if (invocation.print && inputFormat === 'text')
+                io.stdout(`${result.text}\n`);
             else
                 io.stdout(localCommand ? `${result.text}\n` : '\n');
             if (streamOutput && invocation.promptSuggestions) {

package/dist/persistence/managed-worktree-store.d.ts

@@ -0,0 +1,41 @@
+import { type ExclusiveFileLeaseHandle } from '../platform/exclusive-file-lease.js';
+type ManagedWorktreeKind = 'workflow' | 'agent' | 'team';
+type ManagedWorktreePolicy = 'ephemeral' | 'durable';
+type ManagedWorktreeState = 'creating' | 'active' | 'releasing' | 'retained' | 'released';
+export interface ManagedWorktreeRecord {
+    version: 1;
+    worktreeId: string;
+    kind: ManagedWorktreeKind;
+    policy: ManagedWorktreePolicy;
+    ownerId: string;
+    repositoryRoot: string;
+    worktreePath: string;
+    branch: string | null;
+    baseCommit: string;
+    state: ManagedWorktreeState;
+    createdAt: string;
+    updatedAt: string;
+    retentionReason?: string;
+}
+export declare class ManagedWorktreeStore {
+    readonly path: string;
+    readonly lockPath: string;
+    readonly projectLockPath: string;
+    private readonly directory;
+    private readonly stateRoot;
+    private readonly repositoryRoot;
+    private readonly worktreeId;
+    private readonly worktreeLease;
+    private readonly projectLease;
+    constructor(stateRoot: string, repositoryRoot: string, worktreeId: string);
+    acquireLease(): Promise<ExclusiveFileLeaseHandle | null>;
+    read(): Promise<ManagedWorktreeRecord>;
+    create(record: ManagedWorktreeRecord): Promise<void>;
+    update(record: ManagedWorktreeRecord): Promise<void>;
+    private withProjectLease;
+    private assertUnreservedPath;
+    private assertStoreIdentity;
+    private assertSameIdentity;
+}
+export {};
+//# sourceMappingURL=managed-worktree-store.d.ts.map

package/dist/persistence/managed-worktree-store.js

@@ -0,0 +1,341 @@
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, opendir } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { writeFileAtomically } from '../platform/atomic-write.js';
+import { ExclusiveFileLease, } from '../platform/exclusive-file-lease.js';
+import { sanitizeProjectPath } from '../platform/project-path-key.js';
+const RECORD_FIELDS = new Set([
+    'version',
+    'worktreeId',
+    'kind',
+    'policy',
+    'ownerId',
+    'repositoryRoot',
+    'worktreePath',
+    'branch',
+    'baseCommit',
+    'state',
+    'createdAt',
+    'updatedAt',
+    'retentionReason',
+]);
+const REQUIRED_FIELDS = [...RECORD_FIELDS].filter((field) => field !== 'retentionReason');
+const ID_PATTERN = /^[a-f0-9]{32,64}$/u;
+const COMMIT_PATTERN = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u;
+const PROJECT_LEASE_ATTEMPTS = 400;
+const PROJECT_LEASE_DELAY_MS = 5;
+const ALLOWED_TRANSITIONS = {
+    creating: new Set(['active', 'retained', 'released']),
+    active: new Set(['releasing', 'retained']),
+    releasing: new Set(['releasing', 'retained', 'released']),
+    retained: new Set(['releasing', 'retained']),
+    released: new Set(['released']),
+};
+function invalidRecord(detail) {
+    return new Error(detail
+        ? `Invalid managed worktree record: ${detail}`
+        : 'Invalid managed worktree record');
+}
+function exactIsoTimestamp(value) {
+    if (typeof value !== 'string')
+        return false;
+    const milliseconds = Date.parse(value);
+    return (!Number.isNaN(milliseconds) &&
+        new Date(milliseconds).toISOString() === value);
+}
+function validText(value, maximumLength, allowedControls = new Set()) {
+    if (typeof value !== 'string' ||
+        value.length === 0 ||
+        value.length > maximumLength) {
+        return false;
+    }
+    return !Array.from(value).some((character) => {
+        const code = character.codePointAt(0) ?? 0;
+        return (code <= 0x1f || code === 0x7f) && !allowedControls.has(code);
+    });
+}
+function isPathWithin(root, candidate) {
+    const path = relative(resolve(root), resolve(candidate));
+    return (path !== '' &&
+        path !== '..' &&
+        !path.startsWith(`..${sep}`) &&
+        !isAbsolute(path));
+}
+function validateRecord(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw invalidRecord();
+    }
+    const record = value;
+    if (Object.keys(record).some((key) => !RECORD_FIELDS.has(key)) ||
+        REQUIRED_FIELDS.some((key) => !(key in record))) {
+        throw invalidRecord('unexpected or missing field');
+    }
+    if (record.version !== 1 ||
+        typeof record.worktreeId !== 'string' ||
+        !ID_PATTERN.test(record.worktreeId) ||
+        (record.kind !== 'workflow' &&
+            record.kind !== 'agent' &&
+            record.kind !== 'team') ||
+        (record.policy !== 'ephemeral' && record.policy !== 'durable') ||
+        !validText(record.ownerId, 256) ||
+        typeof record.repositoryRoot !== 'string' ||
+        !isAbsolute(record.repositoryRoot) ||
+        resolve(record.repositoryRoot) !== record.repositoryRoot ||
+        typeof record.worktreePath !== 'string' ||
+        !isAbsolute(record.worktreePath) ||
+        resolve(record.worktreePath) !== record.worktreePath ||
+        (record.branch !== null && !validText(record.branch, 256)) ||
+        typeof record.baseCommit !== 'string' ||
+        !COMMIT_PATTERN.test(record.baseCommit) ||
+        !['creating', 'active', 'releasing', 'retained', 'released'].includes(String(record.state)) ||
+        !exactIsoTimestamp(record.createdAt) ||
+        !exactIsoTimestamp(record.updatedAt) ||
+        Date.parse(record.updatedAt) < Date.parse(record.createdAt) ||
+        (record.retentionReason !== undefined &&
+            !validText(record.retentionReason, 2048, new Set([0x09, 0x0a, 0x0d]))) ||
+        (record.state === 'retained' && record.retentionReason === undefined) ||
+        (record.state !== 'retained' && record.retentionReason !== undefined)) {
+        throw invalidRecord();
+    }
+    const kindRoot = join(record.repositoryRoot, '.praxis', 'worktrees', record.kind);
+    if (!isPathWithin(kindRoot, record.worktreePath)) {
+        throw invalidRecord('worktree path is outside its kind root');
+    }
+    return record;
+}
+async function assertDirectoryChain(path, root) {
+    const chain = [];
+    let current = resolve(path);
+    const boundary = resolve(root);
+    for (;;) {
+        chain.unshift(current);
+        if (current === boundary)
+            break;
+        const parent = resolve(current, '..');
+        if (parent === current) {
+            throw new Error('Managed worktree state path escapes its root');
+        }
+        current = parent;
+    }
+    for (const candidate of chain) {
+        try {
+            const entry = await lstat(candidate);
+            if (entry.isSymbolicLink()) {
+                throw new Error(`Managed worktree state path must not contain a symlink: ${candidate}`);
+            }
+            if (!entry.isDirectory()) {
+                throw new Error(`Managed worktree state path must contain only directories: ${candidate}`);
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+}
+async function prepareDirectory(path, root) {
+    await assertDirectoryChain(path, root);
+    await mkdir(path, { recursive: true, mode: 0o700 });
+    await assertDirectoryChain(path, root);
+}
+async function readRegularFile(path, description) {
+    let handle;
+    try {
+        handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            throw new Error(`${description} is missing`);
+        }
+        if (error.code === 'ELOOP') {
+            throw new Error(`${description} must be a regular file`);
+        }
+        throw error;
+    }
+    try {
+        if (!(await handle.stat()).isFile()) {
+            throw new Error(`${description} must be a regular file`);
+        }
+        return await handle.readFile({ encoding: 'utf8' });
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function readRecord(path) {
+    let value;
+    try {
+        value = JSON.parse(await readRegularFile(path, 'Managed worktree record'));
+    }
+    catch (error) {
+        throw invalidRecord(error instanceof Error ? error.message : String(error));
+    }
+    return validateRecord(value);
+}
+function managedWorktreeRecordPath(stateRoot, repositoryRoot, worktreeId) {
+    if (typeof stateRoot !== 'string' || stateRoot.trim() === '') {
+        throw invalidRecord('state root must be non-empty');
+    }
+    if (!isAbsolute(repositoryRoot) ||
+        resolve(repositoryRoot) !== repositoryRoot ||
+        !ID_PATTERN.test(worktreeId)) {
+        throw invalidRecord();
+    }
+    return resolve(stateRoot, 'managed-worktrees', sanitizeProjectPath(repositoryRoot), `${worktreeId}.json`);
+}
+export class ManagedWorktreeStore {
+    path;
+    lockPath;
+    projectLockPath;
+    directory;
+    stateRoot;
+    repositoryRoot;
+    worktreeId;
+    worktreeLease;
+    projectLease;
+    constructor(stateRoot, repositoryRoot, worktreeId) {
+        this.stateRoot = resolve(stateRoot);
+        this.repositoryRoot = repositoryRoot;
+        this.worktreeId = worktreeId;
+        this.path = managedWorktreeRecordPath(stateRoot, repositoryRoot, worktreeId);
+        this.directory = resolve(this.path, '..');
+        this.lockPath = join(this.directory, `${worktreeId}.lock`);
+        this.projectLockPath = join(this.directory, '.registry.lock');
+        this.worktreeLease = new ExclusiveFileLease(this.lockPath);
+        this.projectLease = new ExclusiveFileLease(this.projectLockPath);
+    }
+    async acquireLease() {
+        await prepareDirectory(this.directory, this.stateRoot);
+        return this.worktreeLease.tryAcquire();
+    }
+    async read() {
+        const record = await readRecord(this.path);
+        this.assertStoreIdentity(record);
+        return record;
+    }
+    async create(record) {
+        this.assertStoreIdentity(validateRecord(record));
+        if (record.state !== 'creating') {
+            throw invalidRecord('new records must start in creating state');
+        }
+        await this.withProjectLease(async () => {
+            try {
+                await lstat(this.path);
+                throw new Error('Managed worktree record already exists');
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT')
+                    throw error;
+            }
+            await this.assertUnreservedPath(record.worktreePath);
+            const committed = await writeFileAtomically(this.path, `${JSON.stringify(record)}\n`, {
+                mode: 0o600,
+                beforeCommit: async () => {
+                    try {
+                        await lstat(this.path);
+                        return false;
+                    }
+                    catch (error) {
+                        if (error.code === 'ENOENT') {
+                            return true;
+                        }
+                        throw error;
+                    }
+                },
+            });
+            if (!committed)
+                throw new Error('Could not write managed worktree record');
+        });
+    }
+    async update(record) {
+        this.assertStoreIdentity(validateRecord(record));
+        await this.withProjectLease(async () => {
+            const current = await readRecord(this.path);
+            this.assertStoreIdentity(current);
+            this.assertSameIdentity(current, record);
+            if (!ALLOWED_TRANSITIONS[current.state].has(record.state)) {
+                throw new Error(`Invalid managed worktree transition: ${current.state} -> ${record.state}`);
+            }
+            if (Date.parse(record.updatedAt) < Date.parse(current.updatedAt)) {
+                throw invalidRecord('updatedAt must not move backwards');
+            }
+            const committed = await writeFileAtomically(this.path, `${JSON.stringify(record)}\n`, {
+                mode: 0o600,
+                beforeCommit: async () => {
+                    try {
+                        const entry = await lstat(this.path);
+                        return entry.isFile() && !entry.isSymbolicLink();
+                    }
+                    catch (error) {
+                        if (error.code === 'ENOENT') {
+                            return false;
+                        }
+                        throw error;
+                    }
+                },
+            });
+            if (!committed)
+                throw new Error('Could not write managed worktree record');
+        });
+    }
+    async withProjectLease(operation) {
+        await prepareDirectory(this.directory, this.stateRoot);
+        let lease = null;
+        for (let attempt = 0; attempt < PROJECT_LEASE_ATTEMPTS; attempt += 1) {
+            lease = await this.projectLease.tryAcquire();
+            if (lease)
+                break;
+            await sleep(PROJECT_LEASE_DELAY_MS);
+        }
+        if (!lease) {
+            throw new Error(`Timed out acquiring managed worktree registry lock: ${this.projectLockPath}`);
+        }
+        try {
+            return await operation();
+        }
+        finally {
+            await lease.release();
+        }
+    }
+    async assertUnreservedPath(worktreePath) {
+        const directory = await opendir(this.directory);
+        for await (const entry of directory) {
+            if (!entry.name.endsWith('.json'))
+                continue;
+            const candidate = await readRecord(join(this.directory, entry.name));
+            if (candidate.repositoryRoot !== this.repositoryRoot) {
+                throw new Error('Managed worktree registry project-key collision');
+            }
+            if (candidate.worktreePath === worktreePath &&
+                candidate.state !== 'released') {
+                throw new Error(`Managed worktree path is already owned: ${worktreePath}`);
+            }
+        }
+    }
+    assertStoreIdentity(record) {
+        if (record.repositoryRoot !== this.repositoryRoot ||
+            record.worktreeId !== this.worktreeId) {
+            throw invalidRecord('record identity does not match its store');
+        }
+    }
+    assertSameIdentity(current, next) {
+        for (const field of [
+            'version',
+            'worktreeId',
+            'kind',
+            'policy',
+            'ownerId',
+            'repositoryRoot',
+            'worktreePath',
+            'branch',
+            'baseCommit',
+            'createdAt',
+        ]) {
+            if (current[field] !== next[field]) {
+                throw invalidRecord(`immutable field changed: ${field}`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=managed-worktree-store.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "praxis-agent",
-  "version": "0.60.0",
+  "version": "0.60.1",
   "description": "Local-first, single-user general agent for the command line.",
   "license": "MIT",
   "author": "wuqisen",