@north-light/crouter 0.3.175 → 0.3.177

package/dist/core/worktree.js

@@ -1,10 +1,12 @@
-import { existsSync, linkSync, mkdirSync, readFileSync, realpathSync, rmSync, rmdirSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
-import { createHash, randomUUID } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, rmdirSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import { dirname, join, resolve } from 'node:path';
 import { gitSync } from './git.js';
 import { crtrHome } from './canvas/paths.js';
 import { getNode, updateNode } from './canvas/index.js';
 import { CONFIG_FILE, CRTR_DIR_NAME, STATE_FILE } from '../types.js';
+import { withExclusiveDirectoryLock } from './exclusive-lock.js';
+import { shellQuote } from '../shared/shell-quote.js';
 export class WorktreeError extends Error {
     code;
     next;
@@ -67,113 +69,23 @@ function checkoutPathForBranch(repoRoot, branch) {
     return null;
 }
 const WORKTREE_LOCK_WAIT_MS = 30_000;
-const WORKTREE_LOCK_POLL_MS = 20;
 const WORKTREE_CLEANUP_TIMEOUT_MS = 5_000;
-function sleepSync(ms) {
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-/** Serialize worktree mutation for one repository across crtr processes. Git's
- * own worktree metadata lock is intentionally short-lived and rejects a second
- * add instead of waiting, so callers take this transaction lock first. */
 function commonGitDir(repoRoot) {
     const commonDir = runGit(repoRoot, ['rev-parse', '--git-common-dir'], 'git_common_dir_failed', 'Inspect the repository git metadata, then retry.');
     return realpathSync(resolve(repoRoot, commonDir));
 }
-function ownerIsAlive(owner) {
-    const pid = Number(owner.split(':', 1)[0]);
-    if (!Number.isSafeInteger(pid) || pid <= 0)
-        return false;
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (err) {
-        return err.code !== 'ESRCH';
-    }
-}
-function reclaimDeadLock(lockPath, incumbent) {
-    // A hard-link claim elects exactly one reclaimer without moving lockPath.
-    // Its inode remains the stale lock even if a new owner appears later.
-    const claimPath = `${lockPath}.reclaim`;
-    try {
-        linkSync(lockPath, claimPath);
-    }
-    catch {
-        // A crashed reclaimer can leave its claim behind. Removing that claim is
-        // safe: it names only the already-dead incumbent, and any live reclaimer
-        // then loses authority because its inode check below fails.
-        try {
-            unlinkSync(claimPath);
-        }
-        catch { /* claimant is still resolving it */ }
-        return;
-    }
-    try {
-        const lock = statSync(lockPath);
-        const claim = statSync(claimPath);
-        if (lock.ino === claim.ino && readFileSync(claimPath, 'utf8') === incumbent && !ownerIsAlive(incumbent)) {
-            unlinkSync(lockPath);
-        }
-    }
-    catch { /* owner or another reclaimer changed state; leave it alone */ }
-    finally {
-        try {
-            unlinkSync(claimPath);
-        }
-        catch { /* a later reclaimer will clear this stale claim */ }
-    }
-}
+/** Serialize worktree mutation for one repository across crtr processes. Git's
+ * own worktree metadata lock is intentionally short-lived and rejects a second
+ * add instead of waiting, so callers take this transaction lock first. */
 function withRepositoryWorktreeLock(repoRoot, action) {
     const commonDir = commonGitDir(repoRoot);
     const lockRoot = `${crtrHome()}/worktree-locks`;
-    const lockName = createHash('sha256').update(commonDir).digest('hex');
-    const lockPath = `${lockRoot}/${lockName}`;
-    const owner = `${process.pid}:${randomUUID()}`;
-    const tempPath = `${lockPath}.${owner}.tmp`;
     mkdirSync(lockRoot, { recursive: true });
-    const deadline = Date.now() + WORKTREE_LOCK_WAIT_MS;
-    for (;;) {
-        // Write the owner before atomically linking it into the contention name;
-        // a killed creator leaves only an ignored temp file, never a partial lock.
-        writeFileSync(tempPath, owner, { flag: 'wx' });
-        try {
-            linkSync(tempPath, lockPath);
-            unlinkSync(tempPath);
-            break;
-        }
-        catch (err) {
-            try {
-                unlinkSync(tempPath);
-            }
-            catch { /* process crash leaves harmless temp */ }
-            if (err.code !== 'EEXIST')
-                throw err;
-            let incumbent;
-            try {
-                incumbent = readFileSync(lockPath, 'utf8');
-            }
-            catch {
-                continue;
-            }
-            if (!ownerIsAlive(incumbent))
-                reclaimDeadLock(lockPath, incumbent);
-            if (Date.now() >= deadline) {
-                throw new WorktreeError('worktree_lock_timeout', `timed out waiting to create a managed worktree in ${commonDir}`, 'Wait for the other managed-worktree operation to finish, then retry.');
-            }
-            sleepSync(WORKTREE_LOCK_POLL_MS);
-        }
-    }
-    try {
-        return action();
-    }
-    finally {
-        // Token-checking release cannot unlock a replacement owner's lock.
-        try {
-            if (readFileSync(lockPath, 'utf8') === owner)
-                unlinkSync(lockPath);
-        }
-        catch { /* already reclaimed after a process-level failure */ }
-    }
+    const lockPath = `${lockRoot}/${createHash('sha256').update(commonDir).digest('hex')}`;
+    return withExclusiveDirectoryLock(lockPath, action, {
+        timeoutMs: WORKTREE_LOCK_WAIT_MS,
+        timeoutError: () => new WorktreeError('worktree_lock_timeout', `timed out waiting to create a managed worktree in ${commonDir}`, 'Wait for the other managed-worktree operation to finish, then retry.'),
+    });
 }
 function registeredWorktree(repoRoot, path, branch) {
     const list = gitSync(['worktree', 'list', '--porcelain'], repoRoot);
@@ -226,7 +138,7 @@ function rollbackManagedWorktreeLocked(wt, pathWasAbsent) {
 export function rollbackManagedWorktree(wt) {
     withRepositoryWorktreeLock(wt.repo_root, () => rollbackManagedWorktreeLocked(wt, false));
 }
-// Fix #330/#331: every crtr process auto-initializes a project scope's
+// Every crtr process auto-initializes a project scope's
 // `.crouter/config.json` (`ensureProjectScope` → `ensureScopeInitialized`)
 // the first time it runs against a project root that has no ancestor
 // `.crouter/` yet — which every fresh managed worktree checkout is, unless
@@ -446,9 +358,6 @@ let worktreeCleanupRunner = defaultWorktreeCleanupRunner;
 export function setWorktreeCleanupRunnerForTest(runner) {
     worktreeCleanupRunner = runner ?? defaultWorktreeCleanupRunner;
 }
-function shellQuote(value) {
-    return `'${value.replaceAll("'", "'\\''")}'`;
-}
 function isValidRegisteredCheckout(output, wt) {
     let path = null;
     let prunable = false;
@@ -696,11 +605,11 @@ export function autoDropCleanManagedWorktreeLocked(nodeId, wt, proof) {
         branch_deleted: true,
     };
 }
-/** `push final`'s escape hatch (#327, #333): a managed worktree that has
+/** `push final`'s escape hatch: a managed worktree that has
  *  nothing to land is auto-dropped instead of blocking on an explicit
  *  `node worktree close` — one the caller may have been told NOT to run
- *  because a manager already landed the same change another way (#327), or
- *  that never had anything to close in the first place (#333, a read-only
+ *  because a manager already landed the same change another way, or
+ *  that never had anything to close in the first place (a read-only
  *  review node). Returns null and changes nothing when the worktree is not
  *  PROVABLY empty-and-clean by `proveCleanEmptyManagedWorktree`, OR when a
  *  concurrent mutation invalidates that proof before the destructive delete

package/dist/daemon/api/bridge.js

@@ -49,7 +49,7 @@ function refuseUpgrade(socket, status, statusText, code, message) {
         `connection: close\r\n\r\n` +
         body;
     // `end(payload)` flushes the full body THEN sends FIN — a bare
-    // `write`+`destroy` can truncate the body for a slow remote peer (review M1).
+    // `write`+`destroy` can truncate the body for a slow remote peer.
     try {
         socket.end(payload);
     }

package/dist/daemon/api/handlers/broker-ops.js

@@ -254,8 +254,7 @@ function settleBroker(nodeId, request) {
         return node.intent === 'refresh' ? { action: 'shutdown' } : { action: 'stay_dormant' };
     }
     const signals = { pushedFinal: request.pushedFinal, askedHuman: request.askedHuman };
-    // These two current-state outcomes were previously duplicated around the
-    // stop guard. They are terminal broker consequences, not Pi decisions.
+    // Two current-state outcomes: terminal broker consequences, not Pi decisions.
     if (signals.pushedFinal || node.status === 'done') {
         clearFault(nodeId);
         if (focusOf(nodeId) !== null)

package/dist/daemon/api/handlers/messages.js

@@ -86,7 +86,7 @@ function parseSchema(raw) {
 function label(text) {
     return text.split('\n')[0].slice(0, 120);
 }
-/** The #341/#343 fail-loud rejection for a deferred immediate message aimed at a
+/** The fail-loud rejection for a deferred immediate message aimed at a
  *  target with no natural cycle ahead of it (done/canceled/finalized). Thrown as
  *  an InputError so `toErrorBody` round-trips the FULL structured payload
  *  (code+message+next) into `ApiError.details`, and the CLI's shared
@@ -207,7 +207,7 @@ async function handleMessage(ctx) {
             data: { situational: true, situationalOnly: true },
         });
     };
-    // #341/#343 deferred guard: a done/canceled/finalized target has no natural
+    // Deferred guard: a done/canceled/finalized target has no natural
     // cycle ahead of it, so a deferred entry would sit unseen forever — reject
     // fail-loud BEFORE any side effect, atomically with the append (the read and
     // the write share one canvas write-lock). Non-deferred tiers deliver directly.

package/dist/daemon/api/handlers/nodes.js

@@ -7,6 +7,7 @@
 //
 // `{id}` is the target node.
 import { readdirSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { appendSituationalContext, closeNode, getNode, listNodes, nowIso, reviveNode, } from '../../../index.js';
 import { assertLaunchModelRegistered, forkNode, resolveProfileId, spawnChild } from '../../../core/runtime/spawn.js';
 import { childrenOf, subscribersOf, subscriptionsOf, setMessageWait, updateNode } from '../../../core/canvas/canvas.js';
@@ -29,6 +30,7 @@ import { BrokerUnreachableError } from '../../../core/runtime/broker-request.js'
 import { isBrokerLive, persistDormantModel, setModelLive } from '../../../core/runtime/model-swap.js';
 import { writeOutputSchema } from '../../../core/runtime/structured-output.js';
 import { claimWarmNode, refillWarmPool, warmPoolEnabled } from '../../../core/runtime/warm-pool.js';
+import { profileHome } from '../../../core/profiles/manifest.js';
 import { fullName } from '../../../core/canvas/labels.js';
 import { getCron } from '../../../core/canvas/crons.js';
 import { cronWakeOrigin } from '../../../core/runtime/bearings.js';
@@ -85,11 +87,31 @@ function parseCreateBody(body) {
     }
     return b;
 }
+/** The directory a new node is pinned to. An explicit `pin_cwd` wins; else a
+ *  managed child inherits its spawner's cwd (which is what keeps a worktree
+ *  node's whole subtree inside that worktree); else the node runs in its
+ *  profile's home. The request's own `cwd` — the caller's directory — is only
+ *  the last resort, for a profile that has no home (notably root).
+ *
+ *  This is the profile→cwd direction: `cwd` selected the profile a moment ago,
+ *  and the profile now supplies where the node runs. Collapsing every create
+ *  under a profile onto one directory is also what keeps the warm pool to one
+ *  spare per profile instead of one per directory anyone happened to spawn from. */
+function resolveNodeCwd(req, parent, profileId, contextCwd) {
+    if (req.pin_cwd !== undefined && req.pin_cwd !== '')
+        return resolve(req.pin_cwd);
+    if (parent != null) {
+        const spawner = getNode(parent);
+        if (spawner !== null)
+            return spawner.cwd;
+    }
+    return profileHome(profileId) ?? contextCwd;
+}
 /** Build the immediate spawn recipe. */
-function buildRecipe(req, parent) {
+function buildRecipe(req, parent, cwd) {
     const recipe = {
         kind: req.kind,
-        cwd: req.cwd ?? process.cwd(),
+        cwd,
         prompt: req.prompt ?? '',
     };
     if (req.mode !== undefined)
@@ -122,7 +144,7 @@ function buildRecipe(req, parent) {
  *  forked conversation, a managed worktree, a caller-pinned node id, a spine
  *  parent — disqualifies it. `kind`, `mode`, `model`, `name`, `situational_context`
  *  and `output_schema` are all applied at claim time and so do not. */
-function warmRequestFor(req) {
+function warmRequestFor(req, cwd, profileId) {
     if (!warmPoolEnabled())
         return null;
     if (req.prefer_warm !== true)
@@ -136,8 +158,8 @@ function warmRequestFor(req) {
     return {
         kind: req.kind,
         mode: (req.mode ?? 'base'),
-        cwd: req.cwd ?? process.cwd(),
-        profile: req.profile,
+        cwd,
+        profileId,
         model: req.model ?? null,
         situationalContext: req.situational_context ?? null,
         name: req.name ?? null,
@@ -184,8 +206,9 @@ export async function handleCreate(ctx, deps = {}) {
     // Resolve and validate the exact launch recipe before the warm pool can claim
     // a spare (or the cold path can create a worktree/node). The registry belongs
     // to this daemon, never to the possibly-remote CLI caller.
-    const cwd = req.cwd ?? process.cwd();
-    const profileId = await resolveProfileId(req.profile, parent ?? null, cwd);
+    const contextCwd = req.cwd ?? process.cwd();
+    const profileId = await resolveProfileId(req.profile, parent ?? null, contextCwd);
+    const cwd = resolveNodeCwd(req, parent, profileId, contextCwd);
     const launch = buildLaunchSpec(req.kind, (req.mode ?? 'base'), {
         lifecycle: req.root === true ? 'resident' : 'terminal',
         hasManager: req.root !== true,
@@ -197,7 +220,7 @@ export async function handleCreate(ctx, deps = {}) {
     // --- Warm path: hand out an already-booted spare instead of paying a full
     //     engine boot. A miss is not a failure — it falls through to the cold
     //     spawn below and mints the spare that serves the NEXT create. ---
-    const warm = warmRequestFor(req);
+    const warm = warmRequestFor(req, cwd, profileId);
     if (warm !== null) {
         const claimed = await claimWarmNode(warm);
         refillWarmPool(warm);
@@ -207,7 +230,7 @@ export async function handleCreate(ctx, deps = {}) {
             return { status: 201, body: detailOf(claimed) };
         }
     }
-    const recipe = buildRecipe(req, parent);
+    const recipe = buildRecipe(req, parent, cwd);
     recipe.readiness = req.root === true ? 'await' : 'launch';
     const result = await spawnChild(recipe);
     if (schema !== null)
@@ -334,7 +357,7 @@ function handleRevive(ctx) {
     const body = ctx.body;
     const resume = body?.resume ?? true;
     const reopen = body?.reopen ?? false;
-    // #339 gate, enforced server-side (the latch clear is a canvas write the CLI
+    // Reopen gate, enforced server-side (the latch clear is a canvas write the CLI
     // caller cannot reach): --reopen CAS-clears a spent `final_report`; the
     // no-reopen path refuses a still-latched node (`node_finalized`). reviveNode
     // keeps its own belt-and-suspenders latch guard under the launch lock.

package/dist/daemon/api/handlers/reports.js

@@ -42,7 +42,7 @@ async function handlePush(ctx) {
     const before = req.tier === 'final' ? getNode(id)?.status : undefined;
     // `final` with an OPEN managed worktree, BEFORE the push/transition (spec
     // §6.2 — worktree fs ops are server-side). A provably-clean, zero-commit
-    // worktree is auto-dropped (#327/#333) so a read-only or already-landed node
+    // worktree is auto-dropped so a read-only or already-landed node
     // can finish without an explicit `node worktree close`; any real unlanded
     // work instead blocks with the parity `open_managed_worktree` error,
     // round-tripped via CrtrError.details so the CLI renders the same InputError

package/dist/daemon/api/handlers/review-comments.js

@@ -2,45 +2,23 @@
 // input and derive authorship; review/comment state remains in the review
 // services and comment delivery remains a post-commit best effort.
 import { randomUUID } from 'node:crypto';
-import { ApiError } from '../../../api/index.js';
 import { getNode } from '../../../core/canvas/canvas.js';
 import { isSafeNodeId } from '../../../core/canvas/paths.js';
 import { createComment, deleteComment, editComment, getComment, listCommentEvents, listComments, listReviewEvents, reopenComment, resolveComment, } from '../../../core/review/comments.js';
 import { withCanvasWrite } from '../../../core/canvas/db.js';
 import { captureAnchorText, requireCurrentDocumentLocked } from '../../../core/review/document.js';
 import { applyRangeBatch } from '../../../core/review/remap.js';
-import { getReview, getReviewByCompanion } from '../../../core/review/store.js';
+import { getReviewByCompanion, requireVisibleReview } from '../../../core/review/store.js';
 import { ReviewOperationError } from '../../../core/review/types.js';
 import { notifyComment } from '../../review/comment-notify.js';
 import { toReviewCommentDTO, toReviewCommentEventDTO } from '../map.js';
+import { invalidRequest as rejectRequest, isRecord, objectBody, requireParam, requiredString, } from './validate.js';
 const COMMENT_ID = /^[a-f0-9]{32}$/;
 const SHA256 = /^[a-f0-9]{64}$/;
 const COMMENT_STATUSES = new Set(['open', 'resolved', 'deleted', 'all']);
 const DELIVER_MODES = new Set(['wake', 'quiet']);
 function invalidRequest(violations) {
-    throw new ApiError(400, 'invalid_request', 'review comment request is invalid', { violations });
-}
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-function objectBody(body, allowed, violations) {
-    if (!isRecord(body)) {
-        violations.push({ field: 'body', problem: 'must be an object', received: body });
-        return {};
-    }
-    for (const key of Object.keys(body)) {
-        if (!allowed.includes(key))
-            violations.push({ field: key, problem: 'is not allowed', received: body[key] });
-    }
-    return body;
-}
-function requiredString(body, field, violations) {
-    const value = body[field];
-    if (typeof value !== 'string' || value.trim() === '') {
-        violations.push({ field, problem: 'must be a non-empty string', ...(value === undefined ? {} : { received: value }) });
-        return undefined;
-    }
-    return value;
+    rejectRequest('review comment request', violations);
 }
 function optionalSha256(body, field, violations) {
     const value = body[field];
@@ -135,27 +113,10 @@ function anchorFrom(value, field, violations) {
     };
 }
 function requireReviewId(ctx, violations) {
-    const reviewId = ctx.params['review_id'];
-    if (reviewId === undefined || !isSafeNodeId(reviewId)) {
-        violations.push({ field: 'review_id', problem: 'must be a safe review id', ...(reviewId === undefined ? {} : { received: reviewId }) });
-        return undefined;
-    }
-    return reviewId;
+    return requireParam(ctx, 'review_id', 'must be a safe review id', isSafeNodeId, violations);
 }
 function requireCommentId(ctx, violations) {
-    const commentId = ctx.params['comment_id'];
-    if (commentId === undefined || !COMMENT_ID.test(commentId)) {
-        violations.push({ field: 'comment_id', problem: 'must be a 32-character lowercase hexadecimal id', ...(commentId === undefined ? {} : { received: commentId }) });
-        return undefined;
-    }
-    return commentId;
-}
-function requireVisibleReview(reviewId) {
-    const review = getReview(reviewId);
-    if (review === null || review.state === 'binding') {
-        throw new ReviewOperationError('unknown_review', 'review was not found', { received: reviewId });
-    }
-    return review;
+    return requireParam(ctx, 'comment_id', 'must be a 32-character lowercase hexadecimal id', (v) => COMMENT_ID.test(v), violations);
 }
 function requireOpenReview(reviewId) {
     const review = requireVisibleReview(reviewId);

package/dist/daemon/api/handlers/reviews.js

@@ -7,70 +7,22 @@ import { isSafeNodeId, reviewResultPath } from '../../../core/canvas/paths.js';
 import { responsePath, reviewPath } from '../../../core/human/convention.js';
 import { ticketDir } from '../../../core/human/root.js';
 import { createReview } from '../../../core/review/birth.js';
-import { readAnchorBase, getReview, getReviewByBridge, listReviews } from '../../../core/review/store.js';
+import { readAnchorBase, getReviewByBridge, listReviews, requireVisibleReview } from '../../../core/review/store.js';
 import { ReviewOperationError } from '../../../core/review/types.js';
 import { cancelReview, submitReviewApproval } from '../../review/finish.js';
 import { toFeedbackResultDTO, toReviewDTO } from '../map.js';
+import { invalidRequest as rejectRequest, objectBody, optionalString, requireParam, requiredString, } from './validate.js';
 const REVIEW_STATES = new Set(['open', 'approved', 'canceled']);
 const CREATE_FIELDS = ['origin_kind', 'origin_node_id', 'file', 'idempotency_key', 'subtitle', 'output_path'];
 const CANCEL_FIELDS = ['reason', 'actor'];
 function invalidRequest(violations) {
-    throw new ApiError(400, 'invalid_request', 'review request is invalid', { violations });
-}
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-function objectBody(body, allowed, violations) {
-    if (!isRecord(body)) {
-        violations.push({ field: 'body', problem: 'must be an object', received: body });
-        return {};
-    }
-    for (const key of Object.keys(body)) {
-        if (!allowed.includes(key))
-            violations.push({ field: key, problem: 'is not allowed', received: body[key] });
-    }
-    return body;
-}
-function requiredString(body, field, violations) {
-    const value = body[field];
-    if (typeof value !== 'string' || value === '') {
-        violations.push({ field, problem: 'must be a non-empty string', ...(value === undefined ? {} : { received: value }) });
-        return undefined;
-    }
-    return value;
-}
-function optionalString(body, field, violations) {
-    const value = body[field];
-    if (value === undefined)
-        return undefined;
-    if (typeof value !== 'string' || value === '') {
-        violations.push({ field, problem: 'must be a non-empty string', received: value });
-        return undefined;
-    }
-    return value;
+    rejectRequest('review request', violations);
 }
 function requireReviewId(ctx, violations) {
-    const reviewId = ctx.params['review_id'];
-    if (reviewId === undefined || !isSafeNodeId(reviewId)) {
-        violations.push({ field: 'review_id', problem: 'must be a safe review id', ...(reviewId === undefined ? {} : { received: reviewId }) });
-        return undefined;
-    }
-    return reviewId;
+    return requireParam(ctx, 'review_id', 'must be a safe review id', isSafeNodeId, violations);
 }
 function requireBridgeNodeId(ctx, violations) {
-    const bridgeNodeId = ctx.params['bridge_node_id'];
-    if (bridgeNodeId === undefined || !isSafeNodeId(bridgeNodeId)) {
-        violations.push({ field: 'bridge_node_id', problem: 'must be a safe node id', ...(bridgeNodeId === undefined ? {} : { received: bridgeNodeId }) });
-        return undefined;
-    }
-    return bridgeNodeId;
-}
-function requireVisibleReview(reviewId) {
-    const review = getReview(reviewId);
-    if (review === null || review.state === 'binding') {
-        throw new ReviewOperationError('unknown_review', 'review was not found', { received: reviewId });
-    }
-    return review;
+    return requireParam(ctx, 'bridge_node_id', 'must be a safe node id', isSafeNodeId, violations);
 }
 function approvedResultPath(review) {
     if (review.origin_kind === 'inline')

package/dist/daemon/api/handlers/validate.d.ts

@@ -0,0 +1,23 @@
+import { isRecord } from '../../../shared/predicates.js';
+import type { RequestContext } from '../router.js';
+export { isRecord };
+export type Violation = {
+    field: string;
+    problem: string;
+    received?: unknown;
+};
+/** Reject the request with every violation collected so far. `subject` names
+ *  what was being parsed, e.g. "review comment request". */
+export declare function invalidRequest(subject: string, violations: Violation[]): never;
+/** Narrow a request body to an object and reject any field outside `allowed`.
+ *  A non-object body yields `{}` so the caller's field reads all miss and
+ *  report their own violations rather than throwing. */
+export declare function objectBody(body: unknown, allowed: readonly string[], violations: Violation[]): Record<string, unknown>;
+/** A required field that must be a string carrying at least one non-whitespace
+ *  character — whitespace alone is not a value. */
+export declare function requiredString(body: Record<string, unknown>, field: string, violations: Violation[]): string | undefined;
+/** `requiredString`'s rule when present; absence is allowed. */
+export declare function optionalString(body: Record<string, unknown>, field: string, violations: Violation[]): string | undefined;
+/** A path parameter that must be present and satisfy `accepts`. `problem`
+ *  describes the shape the caller failed to supply. */
+export declare function requireParam(ctx: RequestContext, field: string, problem: string, accepts: (value: string) => boolean, violations: Violation[]): string | undefined;

package/dist/daemon/api/handlers/validate.js

@@ -0,0 +1,58 @@
+// Shared wire-request validation for the daemon's `/v1` handlers.
+//
+// A handler collects `Violation`s while parsing a request, then calls
+// `invalidRequest` once so a caller sees every problem with its body in a
+// single 400 rather than one per round trip.
+import { ApiError } from '../../../api/index.js';
+import { isRecord } from '../../../shared/predicates.js';
+export { isRecord };
+/** Reject the request with every violation collected so far. `subject` names
+ *  what was being parsed, e.g. "review comment request". */
+export function invalidRequest(subject, violations) {
+    throw new ApiError(400, 'invalid_request', `${subject} is invalid`, { violations });
+}
+/** Narrow a request body to an object and reject any field outside `allowed`.
+ *  A non-object body yields `{}` so the caller's field reads all miss and
+ *  report their own violations rather than throwing. */
+export function objectBody(body, allowed, violations) {
+    if (!isRecord(body)) {
+        violations.push({ field: 'body', problem: 'must be an object', received: body });
+        return {};
+    }
+    for (const key of Object.keys(body)) {
+        if (!allowed.includes(key))
+            violations.push({ field: key, problem: 'is not allowed', received: body[key] });
+    }
+    return body;
+}
+/** A required field that must be a string carrying at least one non-whitespace
+ *  character — whitespace alone is not a value. */
+export function requiredString(body, field, violations) {
+    const value = body[field];
+    if (typeof value !== 'string' || value.trim() === '') {
+        violations.push({ field, problem: 'must be a non-empty string', ...(value === undefined ? {} : { received: value }) });
+        return undefined;
+    }
+    return value;
+}
+/** `requiredString`'s rule when present; absence is allowed. */
+export function optionalString(body, field, violations) {
+    const value = body[field];
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || value.trim() === '') {
+        violations.push({ field, problem: 'must be a non-empty string', received: value });
+        return undefined;
+    }
+    return value;
+}
+/** A path parameter that must be present and satisfy `accepts`. `problem`
+ *  describes the shape the caller failed to supply. */
+export function requireParam(ctx, field, problem, accepts, violations) {
+    const value = ctx.params[field];
+    if (value === undefined || !accepts(value)) {
+        violations.push({ field, problem, ...(value === undefined ? {} : { received: value }) });
+        return undefined;
+    }
+    return value;
+}

package/dist/daemon/api/map.js

@@ -259,6 +259,7 @@ export function toProfileDTO(entry) {
         id: entry.profileId,
         name: entry.manifest.name,
         projects: [...entry.manifest.projects],
+        home: entry.manifest.home,
         default_dir: null,
     };
 }

package/dist/daemon/cron-run.js

@@ -377,8 +377,7 @@ async function disposeSettledRun(c, ctx, outOfBand, selfCanceled = false) {
 }
 /** The shared delivering tail of `always` and a CHANGED `on-change`: push
  *  stdout to the armed sink, or take the failure path when the sink is
- *  undeliverable. (The two cases used to share a commented, lint-suppressed
- *  switch fallthrough.) */
+ *  undeliverable. */
 async function deliverOrEscalate(c, ctx, outOfBand, prefix) {
     if (ctx.stdoutHead.trim() === '') {
         return { delivered: `${prefix}empty stdout — nothing delivered`, paused: false };
@@ -464,8 +463,9 @@ export function recoverStaleCronLeases(now, options = {}) {
 }
 /** Wait for a SIGTERMed stale-lease run to actually die, escalating to SIGKILL
  *  if it does not — the same bound `killWithEscalation` gives a live timeout.
- *  Recovery used to record the run as finished the instant it signaled, while a
- *  signal-trapping command was still running and still producing side effects. */
+ *  Recovery must not record the run as finished the instant it signals: a
+ *  signal-trapping command can still be running and still producing side
+ *  effects. */
 async function awaitLeasedRunDeath(c) {
     const deadline = Date.now() + CRON_KILL_GRACE_MS;
     while (Date.now() < deadline) {
@@ -477,7 +477,7 @@ async function awaitLeasedRunDeath(c) {
 }
 /** Settle a stale lease whose process can no longer be observed: the daemon
  *  life that owned this run ended (SIGKILL, host reboot) and nothing recorded
- *  the outcome. Releasing the lease — all this used to do — is wrong twice.
+ *  the outcome. Releasing the lease and nothing else is wrong twice.
  *
  *  1. The run must leave a RECORD. The run log's whole justification is "it
  *     silently stopped working Tuesday"; a hole exactly where the crash
@@ -799,8 +799,8 @@ export function executeCron(c, opts) {
             }
             catch (err) {
                 // Unparseable recurrence. This row can never be scheduled again as
-                // written — but DELETING it (what this used to do) destroys the user's
-                // config AND its whole run history with no record and no escalation, the
+                // written — but DELETING it would destroy the user's config AND its
+                // whole run history with no record and no escalation, the
                 // one outcome the spec has no vocabulary for. Take the failure path
                 // instead: kill the just-started run and hand `close` a process error, so
                 // the row PAUSES and an escalation node arrives holding the parse error.

package/dist/daemon/human/finish.js

@@ -3,7 +3,8 @@ import { ApiError } from '../../api/index.js';
 import { getNode, subscribersOf } from '../../core/canvas/canvas.js';
 import { ticketDir } from '../../core/human/root.js';
 import { cancelTicket, projectReviewOutput, readTicketResult, takeoverAndCompleteDeck, } from '../../core/human/tickets.js';
-import { readJson, responsePath } from '../../core/human/convention.js';
+import { responsePath } from '../../core/human/convention.js';
+import { readJsonOrNull } from '../../core/fs-utils.js';
 import { appendInbox } from '../../core/feed/inbox.js';
 import { FinalDeliveryError, pushFinal } from '../../core/feed/feed.js';
 import { transition } from '../../core/runtime/lifecycle.js';
@@ -67,7 +68,7 @@ export async function cancelHumanTicket(nodeId, opts) {
  */
 export async function deliverTerminalResult(nodeId) {
     const dir = ticketDir(nodeId);
-    const run = readJson(join(dir, 'run.json'));
+    const run = readJsonOrNull(join(dir, 'run.json'));
     if (run?.mode === 'notify')
         return false;
     const result = readTicketResult(dir);