Skip to content

Commit f4c7ea0

Browse files
committed
🐛 Explain joined REPL entry failures in Journal reads
1 parent 25368ab commit f4c7ea0

7 files changed

Lines changed: 907 additions & 22 deletions

File tree

‎architecture.md‎

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8504,7 +8504,7 @@ Raw `DurableEvent`s still terminate at the model.
85048504
`sidekick/entry-inspection.ts` owns entry selection, Source/Prompt/Output windows
85058505
and the complete Journal value. The root's `inspectJournal` operation takes one
85068506
fresh acknowledged reading for both the response component and passive attachment.
8507-
It builds `{entry,status,failure,prompts,records}`, evaluates ordinary yq over
8507+
It builds `{entry,status,failure,prompts,records,execution}`, evaluates ordinary yq over
85088508
that complete permitted value with the existing core evaluator, then pages the
85098509
selected result. Every success is exactly `{value,next,prev,last}`. Small results
85108510
keep their JSON type; selected strings use 4096-code-point windows and arrays use
@@ -8513,6 +8513,26 @@ indivisible array items refuse with a narrower-query direction. Direct channel
85138513
selection remains fully pageable. Source, Prompt and Output keep their existing
85148514
contracts and exact live-output ownership.
85158515

8516+
Journal keeps retained `status` and `failure` separate from `execution`, this
8517+
session's observation of the selected admitted entry. Its `joined` is false
8518+
until that exact task and all owned cleanup join, true afterwards, and null
8519+
without a host observation. Only a joined observation supplies `outcome`
8520+
(`completed`, `failed` or `interrupted`); only a failed one supplies detached
8521+
`error` name/message. A body result or retained Close does not prove join.
8522+
Stop and cleanup failures keep the existing execution failure precedence, so a
8523+
retained success can stand beside a failed execution observation.
8524+
8525+
The session retains only detached permitted observations by entry until its own
8526+
teardown. Error details are cleared through the original entry's existing
8527+
secret policy while available. Unavailable or failed clearance uses exactly
8528+
`{name:"Error",message:"Execution error details were withheld because disclosure checks could not complete."}`.
8529+
No stack, cause, scanner or execution capability enters this value. A later
8530+
response policy clears no earlier error. Both Journal consumers read the same
8531+
observation; disconnecting a reader loses none of it, while losing the root
8532+
loses it all. Cold reading reports unknown even for a completed retained entry.
8533+
No observation appends a terminal or changes repository admission. The Journal
8534+
remains the only durable truth.
8535+
85168536
The feature-local `sidekick/journal-query.ts` formats navigation as ordinary yq
85178537
with an always-true literal JSON header, a resolved-positive-entry guard, the
85188538
opaque original expression and a finite slice. It recognizes only that exact
@@ -8525,7 +8545,7 @@ a successful expression with no usable array/string base is an ordinary fresh
85258545
query. Edited or noncanonical expressions retain ordinary query behavior.
85268546

85278547
Every page request recomputes against that entry's current complete retained
8528-
facts. Callers reuse the same positive entry number; later admissions cannot
8548+
facts and host observation. Callers reuse the same positive entry number; later admissions cannot
85298549
retarget generated windows, and growth may shift pages. Query text and this
85308550
request's current data supply all navigation context: no issued association,
85318551
cache, snapshot, extra record or second execution owner exists. Both evaluations

‎packages/cli/src/documents/sidekick/recovery.md‎

Lines changed: 40 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -35,8 +35,8 @@ prepare.
3535
does not undo an earlier success — so correct the failure that happened
3636
without repeating the work that already did.
3737
- Start a failed entry at its Journal. `<REPL.Entry.Journal entry={2} />`
38-
selects that entry's complete failure, prompt counts and saved records under
39-
`value`. If the result exceeds the response bound, select the relevant records
38+
selects that entry's retained failure, prompt counts, saved records and host
39+
execution observation under `value`. If the result exceeds the response bound, select the relevant records
4040
or a command channel with `yq` as shown below.
4141
- Distinguish commands from agent turns and document output. An `exec` record's
4242
`.exec.exitCode` is the actual saved command exit; its protocol `status: "ok"`
@@ -67,15 +67,49 @@ prepare.
6767
empty string is a turn that recorded emptiness.
6868
- `status: "running"` is the entry this process is executing now. `unfinished`
6969
is an entry whose outcome was never recorded, which is what an interrupted
70-
run leaves behind. Neither is a failure, and a read waits for neither.
70+
run leaves behind. Neither status establishes the execution outcome; read
71+
`execution` for host knowledge. A read waits for neither.
7172
- Reading performs nothing. No read opens an entry, resumes one, runs its
7273
source or asks an agent anything, so an entry you inspect is left exactly as
7374
it was.
7475
- When the host cannot establish what happened, it refuses rather than guessing,
7576
and says so. That refusal is the answer — do not retry the same request hoping
7677
for a different reading of the same records.
77-
- Reopening by itself starts nothing. Nothing is submitted and no turn is taken
78-
until the person asks for something.
78+
- Passive Sidekick conversation reconstruction sends no turn. Opening an
79+
unfinished entry execution is different: it can run unrecorded work after
80+
restoring the saved prefix. Do not use reopen or resend as a diagnostic.
81+
82+
## A joined failure with unfinished history
83+
84+
Read both facts for the exact positive entry number:
85+
86+
```xmd
87+
<REPL.Entry.Source entry={2} />
88+
<REPL.Entry.Journal entry={2} yq="{status, failure, execution}" />
89+
```
90+
91+
A later connection to the same live root can report `status: "unfinished"`,
92+
`failure: null` and `execution: {joined: true, outcome: "failed", error: ...}`.
93+
The error describes the actual joined failure under that entry's disclosure
94+
policy. The Journal has no terminal Close; the host observation does not add one.
95+
Error details may be withheld even when the original submitter received them.
96+
The fixed withholding message is "Execution error details were withheld because
97+
disclosure checks could not complete." It is not the original failure.
98+
99+
For example, source entering checkout B through Dir still uses the session's
100+
selected repository A. A repository-context refusal does not select B. Read the
101+
Source and disclosed error, preserve the completed effects and explain that
102+
Entry Stop refuses because no task remains and the unfinished segment permits
103+
no successor. Do not blindly resend or reopen the same source. This diagnostic
104+
provides no in-place recovery action for that refusal.
105+
106+
`execution.joined: false` means work or cleanup is still live. Inspect without
107+
stopping it; Sidekick `busy: false` does not prove the entry ended. After exact
108+
join, outcome is `completed`, `failed` or `interrupted`. A retained successful
109+
terminal can stand beside failed execution when cleanup failed. With no host
110+
observation, including passive cold reading, all three execution members are
111+
null. Preserve that uncertainty. An ended attachment refuses and starts no
112+
replacement; a cold reader cannot recover the lost host verdict.
79113

80114
## Example
81115

@@ -123,7 +157,7 @@ record, use its `prompt` number to read the saved turn:
123157

124158
## Reading more than one page
125159

126-
Journal applies `yq` to the complete permitted retained entry before paging its
160+
Journal applies `yq` to the complete permitted entry value before paging its
127161
result. You can search all records or all retained channel text in one query.
128162
Small results keep their exact JSON type. A large object or indivisible array
129163
item refuses with a narrower-query direction; directly selected strings remain

‎packages/cli/src/repl/session.ts‎

Lines changed: 99 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,14 @@ import {
7676
withResolvers,
7777
} from "effection";
7878
import type { Operation, Result, Stream, Task } from "effection";
79-
import { INLINE_SOURCE_PATH, inlineSource, validateDocument } from "@executablemd/core";
79+
import {
80+
Component,
81+
INLINE_SOURCE_PATH,
82+
inlineSource,
83+
scanSecrets,
84+
secretPolicy,
85+
validateDocument,
86+
} from "@executablemd/core";
8087
import type { DocumentValidationDiagnostic, Json, PermissionMode } from "@executablemd/core";
8188
import type { GeneratedSelection } from "@executablemd/core/api";
8289
import { API, Permissions } from "@executablemd/runtime";
@@ -226,6 +233,18 @@ export interface ReplOverlay {
226233
readonly draft: string | undefined;
227234
}
228235

236+
/** This session's joined observation, separate from an entry's retained terminal. */
237+
export type ReplEntryExecution = {
238+
readonly joined: boolean | null;
239+
readonly outcome: "completed" | "failed" | "interrupted" | null;
240+
readonly error: { readonly name: string; readonly message: string } | null;
241+
};
242+
243+
const WITHHELD_EXECUTION_ERROR = Object.freeze({
244+
name: "Error",
245+
message: "Execution error details were withheld because disclosure checks could not complete.",
246+
});
247+
229248
/**
230249
* What expansion is doing, for a view that only needs to say so.
231250
*
@@ -393,6 +412,8 @@ export interface ReplSession {
393412
* {@link ReplPrinting} for why the overlay is not this.
394413
*/
395414
readonly printing: ReplPrinting | undefined;
415+
/** Detached observations of admitted entries, retained only by this session. */
416+
readonly executions: Readonly<Record<string, ReplEntryExecution>>;
396417
readonly commandOutput: readonly ReplCommandOutput[];
397418
/**
398419
* What this process is doing element by element, for the entry that is open.
@@ -826,6 +847,10 @@ function* start(
826847
let admitting = true;
827848
/** How the last entry to finish finished. */
828849
let finished: Result<unknown> | undefined;
850+
const executions = new Map<string, ReplEntryExecution>();
851+
yield* ensure(() => {
852+
executions.clear();
853+
});
829854
/**
830855
* Every retained position, taken at the whole file rather than at the
831856
* selected prefix. Rebuilt with the model, so a wake that moves one moves
@@ -1018,6 +1043,9 @@ function* start(
10181043
// the record that outcome carries.
10191044
return live && running !== undefined ? { entry: running.key, output } : undefined;
10201045
},
1046+
get executions() {
1047+
return Object.freeze(Object.fromEntries(executions));
1048+
},
10211049
get commandOutput() {
10221050
return Object.freeze(
10231051
[...commandOutput].map(([entry, chunks]) =>
@@ -1533,6 +1561,35 @@ function* start(
15331561
* reading to find.
15341562
*/
15351563
let placed = false;
1564+
let disclosed: ReplEntryExecution["error"] = null;
1565+
const disclosure: ExecutionInstallation = {
1566+
*install() {
1567+
yield* Component.around({
1568+
*expand([request], next) {
1569+
try {
1570+
yield* next(request);
1571+
} catch (error) {
1572+
disclosed = null;
1573+
if (error instanceof Error) {
1574+
const details = Object.freeze({ name: error.name, message: error.message });
1575+
try {
1576+
const policy = yield* secretPolicy();
1577+
if (
1578+
!policy.enabled ||
1579+
(yield* scanSecrets(JSON.stringify(details))).length === 0
1580+
) {
1581+
disclosed = details;
1582+
}
1583+
} catch {
1584+
// Failure to clear an observation never replaces the execution's failure.
1585+
}
1586+
}
1587+
throw error;
1588+
}
1589+
},
1590+
});
1591+
},
1592+
};
15361593
/** Whether this entry put the session into a stop it must undo. */
15371594
let armed = false;
15381595
function admit(outcome: Result<void>): void {
@@ -1692,6 +1749,7 @@ function* start(
16921749
(text) => {
16931750
finalOutput = Ok(Object.freeze({ entry: key, output: text }));
16941751
},
1752+
disclosure,
16951753
workspace,
16961754
);
16971755
if (!outcome.ok && !finalOutput.ok) {
@@ -1720,10 +1778,48 @@ function* start(
17201778
},
17211779
place: () => {
17221780
placed = true;
1781+
executions.set(key, Object.freeze({ joined: false, outcome: null, error: null }));
17231782
},
17241783
placed: () => placed,
17251784
};
17261785
running = started;
1786+
owner.run(function* () {
1787+
const outcome = yield* started.finished;
1788+
let interrupted = false;
1789+
let failure = outcome.ok ? undefined : outcome.error;
1790+
try {
1791+
yield* started.task.halt();
1792+
const stopped = started.stopped === undefined ? undefined : yield* started.stopped;
1793+
const output = started.output();
1794+
const entry = projectRepl(retained);
1795+
const cancelled =
1796+
entry.ok &&
1797+
entry.value.entries.find((one) => one.key === key)?.terminal?.status === "cancelled";
1798+
interrupted = stopped?.ok === true && output.ok && cancelled;
1799+
failure =
1800+
!outcome.ok && !interrupted ? outcome.error : !output.ok ? output.error : undefined;
1801+
} catch (error) {
1802+
failure = error instanceof Error ? error : new Error(String(error));
1803+
}
1804+
if (placed) {
1805+
executions.set(
1806+
key,
1807+
Object.freeze({
1808+
joined: true,
1809+
outcome:
1810+
failure === undefined ? (interrupted ? "interrupted" : "completed") : "failed",
1811+
error:
1812+
failure === undefined
1813+
? null
1814+
: disclosed?.name === failure.name && disclosed.message === failure.message
1815+
? disclosed
1816+
: WITHHELD_EXECUTION_ERROR,
1817+
}),
1818+
);
1819+
changes.send(model);
1820+
}
1821+
disclosed = null;
1822+
});
17271823
return started;
17281824
}
17291825

@@ -1791,6 +1887,7 @@ function* start(
17911887
*/
17921888
supplyStop: (stop: ReplEntryStop) => void,
17931889
observedOutput: (text: string) => void,
1890+
disclosure: ExecutionInstallation,
17941891
workspace?: true,
17951892
): Operation<Result<unknown>> {
17961893
try {
@@ -1897,7 +1994,7 @@ function* start(
18971994
// Installed into this exact execution, and nowhere else: the live
18981995
// observer and the permission policy are this session's, not the
18991996
// process's, and the attachment carries the entry whose turns they are.
1900-
[...installations, lifecycle.installation, installation, ...owned],
1997+
[...installations, lifecycle.installation, installation, ...owned, disclosure],
19011998
{ initialBindings },
19021999
);
19032000
// This entry's own stop, by value, as soon as there is an execution to

‎packages/cli/src/repl/sidekick/entry-inspection.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,7 @@ import type { Json } from "@executablemd/core";
4747
import { queryJournal } from "./journal-query.ts";
4848

4949
import type { ReplAgentTurn, ReplEntry, ReplPosition, ReplRecord } from "../model.ts";
50+
import type { ReplEntryExecution } from "../session.ts";
5051

5152
/** Why one inspection could not be performed. */
5253
export class EntryInspectionError extends Error {
@@ -68,8 +69,9 @@ export type PromptStatus = "completed" | "failed" | "cancelled";
6869
/** Which of a saved turn's three texts a Prompt read asks for. */
6970
export type PromptField = "reply" | "request" | "error";
7071

71-
/** What one inspection reads: the acknowledged entries, and what is printing. */
72+
/** One acknowledged reading and detached host observations; cold reads have no executions. */
7273
export interface InspectedHistory {
74+
readonly executions?: Readonly<Record<string, ReplEntryExecution>>;
7375
readonly joined?: { readonly entry: string; readonly output: string };
7476
readonly entries: readonly ReplEntry[];
7577
/**
@@ -334,6 +336,7 @@ export function* readEntryJournal(
334336
entry: entry.order,
335337
status: statusOf(entry, history.printing),
336338
failure: entry.terminal?.message ?? null,
339+
execution: history.executions?.[entry.key] ?? { joined: null, outcome: null, error: null },
337340
prompts: countPrompts(entry.turns),
338341
records: entry.records.map((record) =>
339342
pageRecord(

‎packages/cli/src/repl/sidekick/requests.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -155,6 +155,7 @@ export function rootReads(
155155
? yield* readEntryJournal(request, {
156156
entries: read.value.model.entries,
157157
printing: session.printing,
158+
executions: session.executions,
158159
})
159160
: read;
160161
},

0 commit comments

Comments
 (0)