owenloop 0.5.22 → 0.5.24

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -85,6 +85,15 @@ export type AgentEvent = {
85
85
  kind: 'needs_input';
86
86
  question: string;
87
87
  }
88
+ /**
89
+ * Sanitized liveness telemetry. It intentionally carries no provider event
90
+ * or response bytes: callers may persist it as recovery control state.
91
+ */
92
+ | {
93
+ kind: 'activity';
94
+ at: number;
95
+ deadlineAt: number;
96
+ }
88
97
  /** The model turn completed (the SDK result message on an in-process SDK
89
98
  * path; `turn/completed` on an app-server path). */
90
99
  | {
@@ -314,6 +323,8 @@ export interface StartArgs {
314
323
  * behavior stands — that is a supported deployment, not a degraded one.
315
324
  */
316
325
  approvals?: ApprovalRequester;
326
+ /** Optional, adapter-resolved provider-silence recovery policy for this firing. */
327
+ recoveryPolicy?: HarnessRecoveryPolicy;
317
328
  }
318
329
  /**
319
330
  * Everything an adapter needs to RESUME an existing session with one message.
@@ -341,7 +352,25 @@ export interface StartArgs {
341
352
  * happened to hold, and it must NOT fall back to a minimal option set on a map
342
353
  * miss.
343
354
  */
344
- export type DeliverArgs = Pick<StartArgs, 'cwd' | 'owenloopMcp' | 'permissions'> & Pick<StartArgs, 'model' | 'effort' | 'approvals'>;
355
+ export type DeliverArgs = Pick<StartArgs, 'cwd' | 'owenloopMcp' | 'permissions'> & Pick<StartArgs, 'model' | 'effort' | 'approvals' | 'recoveryPolicy'>;
356
+ /** The neutral part of an adapter's opt-in silence recovery configuration. */
357
+ export interface HarnessRecoveryPolicy {
358
+ /** Maximum interval with no raw provider message before a turn is interrupted. */
359
+ idleTimeoutMs: number;
360
+ }
361
+ export declare const HARNESS_FAILURE_CATEGORIES: readonly ["idle-timeout", "authentication", "permission-policy", "model-unavailable", "configuration", "provider"];
362
+ export type HarnessFailureCategory = (typeof HARNESS_FAILURE_CATEGORIES)[number];
363
+ /** A structured adapter failure whose category is safe to persist and render. */
364
+ export declare class HarnessTurnError extends Error {
365
+ readonly category: HarnessFailureCategory;
366
+ readonly terminal: boolean;
367
+ constructor(category: HarnessFailureCategory, terminal: boolean, message: string);
368
+ }
369
+ /** Provider silence while a recovery-enabled turn was awaiting a raw message. */
370
+ export declare class HarnessIdleTimeoutError extends HarnessTurnError {
371
+ constructor(idleTimeoutMs: number);
372
+ }
373
+ export declare function isHarnessTurnError(err: unknown): err is HarnessTurnError;
345
374
  /**
346
375
  * One harness implementation.
347
376
  *
@@ -369,6 +398,12 @@ export interface HarnessAdapter {
369
398
  /** Registry key — the adapter's own harness id. Stable across versions. */
370
399
  id: string;
371
400
  resumeTier: ResumeTier;
401
+ /**
402
+ * Reads and validates adapter-owned recovery configuration. The worker calls
403
+ * it exactly once per firing and passes the resulting neutral policy back to
404
+ * every provider dispatch.
405
+ */
406
+ recoveryPolicy?(): HarnessRecoveryPolicy | undefined;
372
407
  /**
373
408
  * Mandatory permission preflight. Returns every restriction this adapter cannot
374
409
  * enforce exactly. The worker calls this before start or resume; a non-empty
@@ -78,6 +78,40 @@ export const NEUTRAL_PERMISSION_MODES = Object.freeze([
78
78
  export function isNeutralPermissionMode(value) {
79
79
  return NEUTRAL_PERMISSION_MODES.includes(value);
80
80
  }
81
+ export const HARNESS_FAILURE_CATEGORIES = [
82
+ 'idle-timeout',
83
+ 'authentication',
84
+ 'permission-policy',
85
+ 'model-unavailable',
86
+ 'configuration',
87
+ 'provider',
88
+ ];
89
+ /** A structured adapter failure whose category is safe to persist and render. */
90
+ export class HarnessTurnError extends Error {
91
+ category;
92
+ terminal;
93
+ constructor(category, terminal, message) {
94
+ super(message);
95
+ this.name = 'HarnessTurnError';
96
+ this.category = category;
97
+ this.terminal = terminal;
98
+ }
99
+ }
100
+ /** Provider silence while a recovery-enabled turn was awaiting a raw message. */
101
+ export class HarnessIdleTimeoutError extends HarnessTurnError {
102
+ constructor(idleTimeoutMs) {
103
+ super('idle-timeout', false, `provider emitted no SDK message for ${idleTimeoutMs}ms`);
104
+ this.name = 'HarnessIdleTimeoutError';
105
+ }
106
+ }
107
+ export function isHarnessTurnError(err) {
108
+ if (typeof err !== 'object' || err === null)
109
+ return false;
110
+ const candidate = err;
111
+ return (typeof candidate.category === 'string' &&
112
+ HARNESS_FAILURE_CATEGORIES.includes(candidate.category) &&
113
+ typeof candidate.terminal === 'boolean');
114
+ }
81
115
  /** The `code` every `ResumeUnavailableError` carries. Match on THIS, not on the class. */
82
116
  export const RESUME_UNAVAILABLE = 'RESUME_UNAVAILABLE';
83
117
  /**
@@ -94,6 +94,13 @@ export interface GateCall {
94
94
  * `unrestricted` declaration may widen audited filesystem reads only.
95
95
  */
96
96
  filesystem?: FilesystemPermission;
97
+ /**
98
+ * The host-owned exact-work-root boundary. This is deliberately separate from
99
+ * an authored filesystem permission: the latter may describe an unrestricted
100
+ * legacy workflow, while this flag is the narrow audit profile that must never
101
+ * be widened by an approval or an SDK shortcut.
102
+ */
103
+ exactWorkdir?: boolean;
97
104
  }
98
105
  /** The gatekeeper's answer. `reason` is written to be shown to a person and to
99
106
  * the agent, so it names the specific thing that triggered it. */
@@ -102,12 +109,26 @@ export type GateVerdict = {
102
109
  } | {
103
110
  decision: 'escalate';
104
111
  reason: string;
112
+ } | {
113
+ decision: 'deny';
114
+ reason: string;
105
115
  };
106
116
  /** Audited built-ins that cannot mutate the filesystem. WebFetch/WebSearch
107
117
  * can read the unrestricted network without weakening a read-only filesystem.
108
118
  * This is the canonical audited read-tool set used by both the adapter's tool
109
119
  * surface and the explicit unrestricted-filesystem containment exception. */
110
120
  export declare const READ_ONLY_TOOLS: ReadonlySet<string>;
121
+ /** The path-bearing built-ins, derived from the same metadata as extraction. */
122
+ export declare const PATH_BEARING_TOOL_NAMES: ReadonlySet<string>;
123
+ /** Fixed, payload-free guidance for the exact audit boundary. */
124
+ export declare const EXACT_WORKDIR_DENIAL_MESSAGE = "The exact work-root policy denied this path-bearing tool call. Work inside the assigned directory, or call the born-bound `ask` tool on the mounted `owenloop` MCP server if the order cannot be completed there.";
125
+ /**
126
+ * Classify a path-bearing call for the host-controlled exact-work-root policy.
127
+ * It deliberately catches model-authored getters/Proxies and path-normalization
128
+ * errors so an unexpected input cannot make a hook throw and leave the SDK
129
+ * waiting for a response.
130
+ */
131
+ export declare function classifyExactWorkdirPath(call: GateCall): GateVerdict;
111
132
  /**
112
133
  * Whether `candidate` resolves inside `root`.
113
134
  *
@@ -63,14 +63,20 @@ export const READ_ONLY_TOOLS = new Set(['Read', 'Glob', 'Grep', 'WebFetch', 'Web
63
63
  * guessed at.
64
64
  */
65
65
  const PATH_ARGS = Object.freeze({
66
- Read: { args: ['file_path'], humanGateSafeRead: true },
67
- Write: { args: ['file_path'] },
68
- Edit: { args: ['file_path'] },
69
- NotebookRead: { args: ['notebook_path'], humanGateSafeRead: true },
70
- NotebookEdit: { args: ['notebook_path'] },
71
- Glob: { args: ['path'], humanGateSafeRead: true },
72
- Grep: { args: ['path'], humanGateSafeRead: true },
66
+ Read: { args: [{ key: 'file_path' }], humanGateSafeRead: true },
67
+ Write: { args: [{ key: 'file_path' }] },
68
+ Edit: { args: [{ key: 'file_path' }] },
69
+ NotebookRead: { args: [{ key: 'notebook_path' }], humanGateSafeRead: true },
70
+ NotebookEdit: { args: [{ key: 'notebook_path' }] },
71
+ // Glob/Grep schemas deliberately default an omitted path to cwd.
72
+ // Empty, non-string, or inaccessible values are NOT that omission.
73
+ Glob: { args: [{ key: 'path', optional: true }], humanGateSafeRead: true },
74
+ Grep: { args: [{ key: 'path', optional: true }], humanGateSafeRead: true },
73
75
  });
76
+ /** The path-bearing built-ins, derived from the same metadata as extraction. */
77
+ export const PATH_BEARING_TOOL_NAMES = new Set(Object.keys(PATH_ARGS));
78
+ /** Fixed, payload-free guidance for the exact audit boundary. */
79
+ export const EXACT_WORKDIR_DENIAL_MESSAGE = 'The exact work-root policy denied this path-bearing tool call. Work inside the assigned directory, or call the born-bound `ask` tool on the mounted `owenloop` MCP server if the order cannot be completed there.';
74
80
  /**
75
81
  * The owenloop MCP mount, which is ALWAYS allowed under every policy.
76
82
  *
@@ -121,6 +127,40 @@ function stringArg(input, key) {
121
127
  const v = input[key];
122
128
  return typeof v === 'string' && v !== '' ? v : undefined;
123
129
  }
130
+ /**
131
+ * Classify a path-bearing call for the host-controlled exact-work-root policy.
132
+ * It deliberately catches model-authored getters/Proxies and path-normalization
133
+ * errors so an unexpected input cannot make a hook throw and leave the SDK
134
+ * waiting for a response.
135
+ */
136
+ export function classifyExactWorkdirPath(call) {
137
+ const spec = PATH_ARGS[call.toolName];
138
+ if (spec === undefined)
139
+ return ALLOW;
140
+ try {
141
+ if (call.blockedPath !== undefined && call.blockedPath !== '') {
142
+ return { decision: 'deny', reason: EXACT_WORKDIR_DENIAL_MESSAGE };
143
+ }
144
+ for (const arg of spec.args) {
145
+ const present = Object.prototype.hasOwnProperty.call(call.input, arg.key);
146
+ if (!present && arg.optional === true)
147
+ continue;
148
+ if (!present)
149
+ return { decision: 'deny', reason: EXACT_WORKDIR_DENIAL_MESSAGE };
150
+ const value = call.input[arg.key];
151
+ if (typeof value !== 'string' || value === '') {
152
+ return { decision: 'deny', reason: EXACT_WORKDIR_DENIAL_MESSAGE };
153
+ }
154
+ if (!isInside(call.workdir, value)) {
155
+ return { decision: 'deny', reason: EXACT_WORKDIR_DENIAL_MESSAGE };
156
+ }
157
+ }
158
+ return ALLOW;
159
+ }
160
+ catch {
161
+ return { decision: 'deny', reason: EXACT_WORKDIR_DENIAL_MESSAGE };
162
+ }
163
+ }
124
164
  /**
125
165
  * Whether `candidate` resolves inside `root`.
126
166
  *
@@ -166,6 +206,13 @@ export function dangerousCommand(command) {
166
206
  export function classifyToolCall(call, policy) {
167
207
  if (call.toolName.startsWith(OWENLOOP_MCP_PREFIX))
168
208
  return ALLOW;
209
+ // This host profile runs before legacy policy semantics. It is intentionally
210
+ // not an escalation: no human approval can widen the exact snapshot boundary.
211
+ if (call.exactWorkdir === true) {
212
+ const exact = classifyExactWorkdirPath(call);
213
+ if (exact.decision === 'deny')
214
+ return exact;
215
+ }
169
216
  if (policy === 'deny-unapproved') {
170
217
  return { decision: 'escalate', reason: `permissionMode denies unapproved tool calls` };
171
218
  }
@@ -178,7 +225,7 @@ export function classifyToolCall(call, policy) {
178
225
  }
179
226
  const pathArgs = PATH_ARGS[call.toolName];
180
227
  const paths = (pathArgs?.args ?? [])
181
- .map((key) => stringArg(call.input, key))
228
+ .map(({ key }) => stringArg(call.input, key))
182
229
  .filter((p) => p !== undefined);
183
230
  // An explicit unrestricted filesystem declaration widens only the declared
184
231
  // boundary of the shared audited read set. It does not change which operation
@@ -1,6 +1,22 @@
1
+ import type { HarnessFailureCategory } from './contract.ts';
1
2
  import { type Liveness } from '../shift/state.ts';
2
3
  /** Where a step attempt is in its life. */
3
4
  export type SessionStatus = 'active' | 'turn-ended' | 'submitted' | 'dead';
5
+ export type RecoveryPhase = 'primary' | 'wake' | 'cold-restart' | 'held';
6
+ /** Fsynced, sanitized control state for a recovery-enabled turn. */
7
+ export interface RecoveryCheckpoint {
8
+ generation: string;
9
+ phase: RecoveryPhase;
10
+ wakeUsed: boolean;
11
+ coldRestartUsed: boolean;
12
+ phaseStartedAt?: number;
13
+ lastActivityAt?: number;
14
+ deadlineAt?: number;
15
+ lastFailure?: {
16
+ category: HarnessFailureCategory;
17
+ at: number;
18
+ };
19
+ }
4
20
  /** One line of `sessions.jsonl`. */
5
21
  export interface SessionRecord {
6
22
  workflow: string;
@@ -62,6 +78,8 @@ export interface SessionRecord {
62
78
  * `attempt` stays outside it, per Phase 1.
63
79
  */
64
80
  deliveredReasonAt?: number;
81
+ /** Present only for opt-in recovery; never contains a prompt, token, or SDK payload. */
82
+ recovery?: RecoveryCheckpoint;
65
83
  updatedAt: number;
66
84
  }
67
85
  export interface SessionStoreOptions {
@@ -154,6 +154,35 @@ function firstInvalidSessionRecordField(v) {
154
154
  return 'key';
155
155
  if (typeof r['status'] !== 'string' || !STATUSES.has(r['status']))
156
156
  return 'status';
157
+ if (r['recovery'] !== undefined) {
158
+ if (typeof r['recovery'] !== 'object' || r['recovery'] === null || Array.isArray(r['recovery']))
159
+ return 'recovery';
160
+ const recovery = r['recovery'];
161
+ if (!isNonEmptyString(recovery['generation']))
162
+ return 'recovery.generation';
163
+ if (!['primary', 'wake', 'cold-restart', 'held'].includes(recovery['phase']))
164
+ return 'recovery.phase';
165
+ if (typeof recovery['wakeUsed'] !== 'boolean')
166
+ return 'recovery.wakeUsed';
167
+ if (typeof recovery['coldRestartUsed'] !== 'boolean')
168
+ return 'recovery.coldRestartUsed';
169
+ for (const field of ['phaseStartedAt', 'lastActivityAt', 'deadlineAt']) {
170
+ if (recovery[field] !== undefined && (!Number.isFinite(recovery[field]) || recovery[field] < 0)) {
171
+ return `recovery.${field}`;
172
+ }
173
+ }
174
+ if (recovery['lastFailure'] !== undefined) {
175
+ if (typeof recovery['lastFailure'] !== 'object' || recovery['lastFailure'] === null || Array.isArray(recovery['lastFailure'])) {
176
+ return 'recovery.lastFailure';
177
+ }
178
+ const failure = recovery['lastFailure'];
179
+ if (!['idle-timeout', 'authentication', 'permission-policy', 'model-unavailable', 'configuration', 'provider'].includes(failure['category'])) {
180
+ return 'recovery.lastFailure.category';
181
+ }
182
+ if (!Number.isFinite(failure['at']) || failure['at'] < 0)
183
+ return 'recovery.lastFailure.at';
184
+ }
185
+ }
157
186
  return null;
158
187
  }
159
188
  /**
@@ -459,7 +488,7 @@ function appendSessionUnlocked(file, rec, opts) {
459
488
  let failure;
460
489
  try {
461
490
  writeFileSync(fd, `${separator}${JSON.stringify(rec)}\n`);
462
- if (rec.status === 'active') {
491
+ if (rec.status === 'active' || rec.recovery !== undefined) {
463
492
  const sync = opts.sync ?? fsyncSync;
464
493
  sync(fd);
465
494
  if (!existed)
@@ -98,7 +98,7 @@ import { effectiveRosterLayers, mergeRosterLayers } from "../settings/roster.js"
98
98
  import { adapterFor, defaultHarnessId, registeredHarnessIds } from "../harness/registry.js";
99
99
  import { parseHarnessCarrier } from "../bundle/fetch.js";
100
100
  import { normalizeStepPermissions, validateHarnessOptions } from "../harness/permissions.js";
101
- import { appendSession, latestForTask, sessionsPath, } from "../harness/session-store.js";
101
+ import { appendSession, latestFor, latestForTask, sessionsPath, } from "../harness/session-store.js";
102
102
  import { ensureWorkDir, resolveAllowedWorkdirRoots, resolveWorkRepo, resolveWorkRoot, } from "../agent/workdir.js";
103
103
  import { resolveShiftId, resolveTarget } from "./hold.js";
104
104
  import { installSignalHandlers } from "./signals.js";
@@ -194,6 +194,7 @@ export function exitCodeFor(outcome) {
194
194
  switch (outcome) {
195
195
  case 'submitted':
196
196
  case 'completed':
197
+ case 'held':
197
198
  return 0;
198
199
  case 'misroute':
199
200
  case 'workdir-denied':
@@ -550,6 +551,9 @@ export async function run(args, deps = {}) {
550
551
  // PHASE 4: the same reader `nextAttempt` uses, handed to the loop whole so
551
552
  // it can decide resume vs cold replay. Reads only; the loop is what writes.
552
553
  latestSession: (task) => latestForTask(sessionsFile, task),
554
+ // Recovery consumption belongs to this concrete hub run. A human retry
555
+ // gets a fresh run id and therefore a fresh bounded recovery budget.
556
+ latestRunSession: (workflow, run, step) => latestFor(sessionsFile, workflow, run, step),
553
557
  sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
554
558
  now: () => Date.now(),
555
559
  out,
@@ -56,6 +56,13 @@ export declare function formatAge(ms: number): string;
56
56
  * LISTING — one bad row must not take down the other rows with it.
57
57
  */
58
58
  export declare function resumeCommandFor(rec: SessionRecord): string | undefined;
59
+ /**
60
+ * Recovery records use an explicit allowlist, unlike legacy local-resume rows.
61
+ * The JSONL reader intentionally preserves forward fields, so exclusion-based
62
+ * redaction would disclose any future/stray prompt, credential, config, token,
63
+ * or failure-prose field that reached the machine-local store.
64
+ */
65
+ export declare function projectSession(rec: SessionRecord): SessionRecord | Record<string, unknown>;
59
66
  /** Render the table. Exported for the unit test; `run` does the I/O. */
60
67
  export declare function renderTable(records: readonly SessionRecord[], now: number): string;
61
68
  export declare function run(args: string[]): Promise<number>;
@@ -107,6 +107,10 @@ function shellQuote(s) {
107
107
  * LISTING — one bad row must not take down the other rows with it.
108
108
  */
109
109
  export function resumeCommandFor(rec) {
110
+ // Recovery control rows are intentionally safe to show to an operator or a
111
+ // script. A provider token would make that guarantee false.
112
+ if (rec.recovery !== undefined)
113
+ return undefined;
110
114
  // An empty token is a real, readable record: the worker writes one before the
111
115
  // harness emits `started`, so a launch that died still leaves proof it existed.
112
116
  // Handing that empty string to `resumeCommand` would print a command that
@@ -124,6 +128,53 @@ export function resumeCommandFor(rec) {
124
128
  return undefined;
125
129
  }
126
130
  }
131
+ function recoverySummary(rec) {
132
+ const state = rec.recovery;
133
+ if (state === undefined)
134
+ return '—';
135
+ const activity = state.lastActivityAt ?? state.deadlineAt;
136
+ return [
137
+ state.phase === 'held' ? 'held: action required' : state.phase,
138
+ `wake=${state.wakeUsed ? 'yes' : 'no'}`,
139
+ `cold=${state.coldRestartUsed ? 'yes' : 'no'}`,
140
+ ...(activity !== undefined ? [`at=${activity}`] : []),
141
+ ...(state.lastFailure !== undefined ? [`failure=${state.lastFailure.category}`] : []),
142
+ ].join(', ');
143
+ }
144
+ /**
145
+ * Recovery records use an explicit allowlist, unlike legacy local-resume rows.
146
+ * The JSONL reader intentionally preserves forward fields, so exclusion-based
147
+ * redaction would disclose any future/stray prompt, credential, config, token,
148
+ * or failure-prose field that reached the machine-local store.
149
+ */
150
+ export function projectSession(rec) {
151
+ if (rec.recovery === undefined)
152
+ return rec;
153
+ const state = rec.recovery;
154
+ return {
155
+ workflow: rec.workflow,
156
+ run: rec.run,
157
+ step: rec.step,
158
+ order: rec.order,
159
+ ...(rec.key !== undefined ? { key: rec.key } : {}),
160
+ attempt: rec.attempt,
161
+ harness: rec.harness,
162
+ status: rec.status,
163
+ createdAt: rec.createdAt,
164
+ ...(rec.deliveredReasonAt !== undefined ? { deliveredReasonAt: rec.deliveredReasonAt } : {}),
165
+ updatedAt: rec.updatedAt,
166
+ recovery: {
167
+ generation: state.generation,
168
+ phase: state.phase,
169
+ wakeUsed: state.wakeUsed,
170
+ coldRestartUsed: state.coldRestartUsed,
171
+ ...(state.phaseStartedAt !== undefined ? { phaseStartedAt: state.phaseStartedAt } : {}),
172
+ ...(state.lastActivityAt !== undefined ? { lastActivityAt: state.lastActivityAt } : {}),
173
+ ...(state.deadlineAt !== undefined ? { deadlineAt: state.deadlineAt } : {}),
174
+ ...(state.lastFailure !== undefined ? { lastFailure: { category: state.lastFailure.category, at: state.lastFailure.at } } : {}),
175
+ },
176
+ };
177
+ }
127
178
  /** Render the table. Exported for the unit test; `run` does the I/O. */
128
179
  export function renderTable(records, now) {
129
180
  const rows = records.map((rec) => [
@@ -133,9 +184,10 @@ export function renderTable(records, now) {
133
184
  rec.status,
134
185
  String(rec.attempt),
135
186
  formatAge(now - rec.updatedAt),
187
+ recoverySummary(rec),
136
188
  resumeCommandFor(rec) ?? '—',
137
189
  ]);
138
- const header = ['ORDER', 'STEP', 'HARNESS', 'STATUS', 'ATTEMPT', 'AGE', 'RESUME'];
190
+ const header = ['ORDER', 'STEP', 'HARNESS', 'STATUS', 'ATTEMPT', 'AGE', 'RECOVERY', 'RESUME'];
139
191
  const widths = header.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? '').length)));
140
192
  // The last column is not padded: trailing spaces on a command an operator is
141
193
  // about to copy are noise, and a resume command can be long.
@@ -170,10 +222,9 @@ export async function run(args) {
170
222
  // one that just failed.
171
223
  visible.sort((a, b) => b.updatedAt - a.updatedAt);
172
224
  if (parsed.json) {
173
- // The RAW records, tokens included. This is machine-local data an operator
174
- // already owns, and withholding the token would make the output useless for
175
- // exactly the scripting this flag exists for.
176
- process.stdout.write(`${JSON.stringify(visible, null, 2)}\n`);
225
+ // Legacy records remain raw for established local-resume scripts. Opt-in
226
+ // recovery rows are a deliberately redacted projection.
227
+ process.stdout.write(`${JSON.stringify(visible.map(projectSession), null, 2)}\n`);
177
228
  return 0;
178
229
  }
179
230
  if (visible.length === 0) {
@@ -123,16 +123,55 @@ The Claude Code adapter refuses a `read-only` allow-list containing anything out
123
123
 
124
124
  ## Owenloop control-plane exception
125
125
 
126
- `network: owenloop-only` means that the Step Agent may reach only the born-bound Owenloop MCP control plane for the held order. The exception exists so the Step Agent can call `get_order` and `submit`; without those calls the Step Agent cannot inspect or complete the order.
126
+ `network: owenloop-only` means that the Step Agent may reach only the born-bound Owenloop MCP control plane for the held order. The exception exists so the Step Agent can call `get_order`, `submit`, and `ask`; without those calls the Step Agent cannot inspect, complete, or honestly hold an impossible order.
127
127
 
128
- For Claude Code isolation, the adapter sets `settingSources: []`, `strictMcpConfig: true`, disables skills, excludes hooks and external MCP servers, and mounts only the worker-created `owenloop` MCP server. The restricted MCP child positively registers exactly `get_order` and `submit`; the restricted MCP child does not register `reject`. A future work-holder tool therefore does not enter restricted sessions unless the adapter explicitly adds the tool to the positive registration list. The adapter also restricts built-in tools to an audited no-network set. The same option construction runs for cold start and resume.
128
+ For Claude Code isolation, the adapter sets `settingSources: []`, `strictMcpConfig: true`, disables skills, excludes hooks and external MCP servers, and mounts only the worker-created `owenloop` MCP server. The restricted MCP child positively registers exactly `get_order`, `submit`, and `ask`; the restricted MCP child does not register `reject`. A future work-holder tool therefore does not enter restricted sessions unless the adapter explicitly adds the tool to the positive registration list. The adapter also restricts built-in tools to an audited no-network set. The same option construction runs for cold start and resume.
129
129
 
130
- The born-bound Owenloop MCP server is created by the worker from the live workflow, run, origin, account, Shift, and held claim. Workflow extension data cannot replace that mount. During isolation, the adapter adds `mcp__owenloop__get_order` and `mcp__owenloop__submit` to `allowedTools` so both control calls execute without an unattended permission prompt. `allowedTools` controls permission automation; `allowedTools` does not filter the MCP server's `tools/list` response. The positive registration list on the MCP child is the visibility boundary. The adapter also adds `mcp__owenloop__reject` to `disallowedTools` as defense in depth. A direct deny or an MCP wildcard deny that blocks Owenloop `get_order` or `submit` is refused.
130
+ The born-bound Owenloop MCP server is created by the worker from the live workflow, run, origin, account, Shift, and held claim. Workflow extension data cannot replace that mount. During isolation, the adapter adds `mcp__owenloop__get_order`, `mcp__owenloop__submit`, and `mcp__owenloop__ask` to `allowedTools` so those control calls execute without an unattended permission prompt. `allowedTools` controls permission automation; `allowedTools` does not filter the MCP server's `tools/list` response. The positive registration list on the MCP child is the visibility boundary. The adapter also adds `mcp__owenloop__reject` to `disallowedTools` as defense in depth. A direct deny or an MCP wildcard deny that blocks Owenloop `get_order`, `submit`, or `ask` is refused.
131
131
 
132
132
  Outside Claude Code isolation, the default work-holder MCP child continues to register `get_order`, `submit`, and `reject`.
133
133
 
134
134
  ## Security boundary
135
135
 
136
+ ### Claude exact work root
137
+
138
+ A dedicated audit Shift may enable `OWENLOOP_CLAUDE_EXACT_WORKDIR=1` in the
139
+ host environment. It is a host-only setting: it is removed before the Claude
140
+ child is launched and is not carried in prompts, events, provider options, or
141
+ durable session records. Absence leaves existing workflows unchanged; any other
142
+ present value fails configuration before a provider query starts.
143
+
144
+ This profile requires an explicit or derived built-in surface containing only
145
+ `Read`, `Glob`, and `Grep` (an explicit `tools: []` remains valid). It forces
146
+ the same isolated settings/MCP/skills profile described above, rejects an
147
+ incompatible authored surface rather than silently filtering it, and keeps the
148
+ born-bound `get_order`, `submit`, and `ask` controls headless.
149
+
150
+ Every path-bearing built-in is intercepted by a host-owned `PreToolUse` guard
151
+ before the SDK's bare `allowedTools` approval can run. A well-formed lexical
152
+ path inside the exact step directory proceeds headlessly. Outside, malformed,
153
+ or SDK-blocked paths are final fixed-message denials: they never create a human
154
+ tool approval, and the agent must work inside the directory or use `ask` when
155
+ the order is impossible there. The callback retains the same final-deny check
156
+ as defense in depth.
157
+
158
+ For a configured model, both cold and resumed strict turns require the provider
159
+ to confirm the identical literal model name. Missing identity, a different
160
+ model, an unavailable model, or a structured fallback event fails the turn
161
+ instead of accepting a substitute. No fallback model is configured.
162
+
163
+ The boundary is lexical containment only; it does not claim to defeat symlinks
164
+ or special files. Snapshot construction remains responsible for those separate
165
+ checks.
166
+
136
167
  `x.harness` permission fields are enforced policy. Adapter preflight must prove that the selected adapter can implement each authored restriction exactly; unsupported policy fails closed.
137
168
 
138
169
  `advisory.tools` is model guidance only. `advisory.tools` does not configure an adapter, does not remove a provider tool, and is not a security boundary.
170
+
171
+ ## Claude SDK idle recovery
172
+
173
+ `OWENLOOP_CLAUDE_IDLE_TIMEOUT_MS` is an opt-in, host-only Claude Code setting. It accepts a canonical decimal duration from `1000` through `3600000` milliseconds; a present invalid value is a typed configuration failure before the model is started. The pilot value is `600000` (ten minutes). The setting is deliberately not passed to the SDK child environment.
174
+
175
+ When enabled, the timer measures silence between raw SDK messages, including partial stream events, rather than total turn time. Recovery logs contain only local lifecycle lines, typed failure categories, and sanitized timestamps: provider session ids, cwd, stderr, result/init prose, assistant/user payloads, and partial events are suppressed. Recovery applies only when the order has exactly one non-empty owed output: it permits a primary turn, one same-session wake, and one cold replay. A submit or other hub outcome wins every race. Authentication, permission-policy, model-unavailable, and configuration failures go straight to a producer-side `ask`; exhausted recovery also holds through `ask` rather than releasing the debt.
176
+
177
+ Phase and consumed wake/cold flags are fsynced before dispatch. A crash may therefore skip a phase but cannot duplicate it; re-dispatch of the same run reads the same checkpoint. A human retry has a new run id and a fresh budget. Once the hub confirms submission or claim loss, the worker stops its lease before provider cleanup; recovery cleanup is best-effort and bounded to five seconds, so a stuck adapter cannot keep heartbeats or ownership semantics alive. `work sessions` shows phase, flags, activity/deadline and typed category for recovery rows, identifies `held` as requiring human action, and redacts the provider token/resume command in both table and JSON output. Start and resume retain the dedicated `CLAUDE_CONFIG_DIR` and `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1` isolation environment.
package/docs/cli.md CHANGED
@@ -3623,6 +3623,10 @@ child's `eligible` orders or wait on child completion. To block on a tree, wait
3623
3623
  on the instance that actually owes the work (often a child), or poll deep
3624
3624
  `tick`/`status` yourself.
3625
3625
 
3626
+ ## Claude idle-recovery status
3627
+
3628
+ For a Shift intentionally using `OWENLOOP_CLAUDE_IDLE_TIMEOUT_MS=600000`, `owenloop work sessions` reports recovery phase (`primary`, `wake`, `cold-restart`, or `held`), wake/cold usage, durable activity/deadline, and typed failure category. `held: action required` means the worker has called the normal producer-side `ask` after an exhausted recovery budget or a terminal/configuration failure; answer/retry the held artifact in the usual way. Recovery applies only to an order with exactly one non-empty owed output. Recovery-enabled rows omit provider tokens and do not print a `RESUME` command; recovery worker logs likewise suppress provider session ids, cwd, stderr, result/init prose, and SDK payloads. The setting is host-only, must be a canonical decimal duration between 1000 and 3600000 ms, and is never copied into the agent child environment.
3629
+
3626
3630
  ## Instance pinning — editing a workflow definition mid-flight
3627
3631
 
3628
3632
  `create` snapshots the fully-expanded definition (post `include:`/`calls:`) onto the
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.22",
3
+ "version": "0.5.24",
4
4
  "description": "Deterministic rails for agentic workflows. Declare steps and dependencies; the engine guarantees order, redoes what changes invalidate, and stops what keeps failing — instead of hoping the agent follows through.",
5
5
  "license": "Apache-2.0",
6
6
  "author": "typicalday",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.22",
3
+ "version": "0.5.24",
4
4
  "description": "Claude Code driver for owenloop — cross-harness shift and conduct skills driven by the owenloop CLI, plus one hub control-plane MCP server backing an author skill and a fallback worker, for conducting and authoring workflows against your hosted owenloop server.",
5
5
  "author": {
6
6
  "name": "Typical Day"
@@ -7,7 +7,7 @@
7
7
  "mcp"
8
8
  ],
9
9
  "env": {
10
- "OWENLOOP_PLUGIN_VERSION": "0.5.22"
10
+ "OWENLOOP_PLUGIN_VERSION": "0.5.24"
11
11
  }
12
12
  }
13
13
  }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "owenloop",
3
- "version": "0.5.22",
3
+ "version": "0.5.24",
4
4
  "description": "Codex plugin for the owenloop workflow engine.",
5
5
  "skills": "./skills/",
6
6
  "mcpServers": "./.mcp.json"
@@ -6,7 +6,7 @@
6
6
  "mcp"
7
7
  ],
8
8
  "env": {
9
- "OWENLOOP_PLUGIN_VERSION": "0.5.22"
9
+ "OWENLOOP_PLUGIN_VERSION": "0.5.24"
10
10
  },
11
11
  "env_vars": [
12
12
  "HOME",