looply-cli 0.0.0-stage → 0.2.0

package/dist/sessions-cmd.d.ts

@@ -0,0 +1,202 @@
+import { type ControlVerdict, type Checkpoint, type CheckpointMeasurements, type DirectionContext, type Instruction, type InstructionResult, type ObservationRecord, type SessionAdoptionVerdict, type SessionClaim, type SessionMeasurements, type WatchWindow } from '@looply/core';
+import { type SessionRecord } from './session-store';
+/**
+ * `looply sessions` — F-14's consumer, and the documented handshake itself.
+ *
+ * 🔴 THE HANDSHAKE IS A FILE, NOT A TERMINAL. The charter forbids seizing one,
+ * so nothing here attaches to a terminal: a session that wants managing WRITES
+ * a claim and points looply at it. There is no path by which looply adopts a
+ * session that did not ask — which is also why the user's own unrelated
+ * sessions are untouched. Not an exclusion list; nothing can reach them.
+ *
+ *   looply sessions                     what this machine knows about
+ *   looply sessions --offer <file>      a session asks to be managed
+ *   looply sessions --ack <id>          the session acknowledges control
+ *   looply sessions --watch <id>        attach a bounded watcher to one
+ *   looply sessions --direct <id>       tell a controlled session to do one thing
+ *   looply sessions --checkpoint <id>   capture what a REFUSED session has done
+ *   looply sessions --observations <id> what earlier watches recorded
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 THERE IS NO `--authorize`, AND ITS ABSENCE IS THE POINT.
+ *
+ * The first version of this had one, and `approval-architecture.spec.ts` was
+ * right to refuse it. Its rule is that the server is the authority, and a file
+ * this machine can write asserting somebody approved is a second answer nobody
+ * gave — the machine holds the filesystem. A local `--authorize` is exactly
+ * that: anyone with a shell could mint the human half of a two-party rule,
+ * offline, and this fold would read it as a person's decision.
+ *
+ * ⚠️ That guard matches on SUBSTRINGS, so it does not distinguish a violation
+ * from a docblock quoting one. Its forbidden tokens are paraphrased here rather
+ * than quoted, deliberately — the first draft of this comment tripped the guard
+ * with the guard's own words.
+ *
+ * So the authorization half has NO LOCAL SOURCE. `controlAuthorized` can only
+ * ever arrive from a server-issued grant, and `serverControl` is how this build
+ * asks for one.
+ *
+ * ⚠️ WHAT REMAINS UNFINISHED IS NARROWER THAN IT WAS, AND SAYING SO PRECISELY
+ * MATTERS — THE OLD WORDING HERE ("this build cannot obtain one yet") SURVIVED
+ * THE PACKET THAT MADE IT FALSE, which is how a finished feature goes on
+ * reading as a missing one. The grant exists, the routes exist, the machine
+ * reads them, and the fold refuses everything it should. The one missing actor
+ * is the session's own ADAPTER: `controlVerdict` accepts only an
+ * acknowledgement that came through it, nothing in the product sends one yet,
+ * and so `controlled` is unreachable end to end BY CONSTRUCTION rather than by
+ * oversight. Sessions top out at observe-only, which is where the charter says
+ * to start — and observe-only now does something: `--watch` attaches a bounded
+ * watcher.
+ */
+export declare const SESSIONS_USAGE: string;
+/**
+ * 🔴 A WATCH IS BOUNDED EVEN WHEN NO GRANT BOUNDS IT.
+ *
+ * A controlled session's watch could take its window from the grant's expiry.
+ * An observe-only one has no grant — observation was never the half that needed
+ * permission — so there is nothing to read a bound off, and "then it runs
+ * forever" is not an acceptable answer to that. The bound is local, it has a
+ * ceiling a flag cannot raise, and the record says what it was.
+ */
+/**
+ * What a watcher needs that is not a bound: WHERE to look, and WHICH process
+ * is the subject.
+ *
+ * 🔴 THE PID TRAVELS WITH THE CALL AND IS NOT RE-DERIVED. The first wiring
+ * of this had the runtime read the pid back off the session ledger, and a live
+ * run found it silently returning nothing — the store had not been opened, so
+ * the probe answered `unknown` forever, `unknown` correctly never ends a watch,
+ * and a watch whose session had been killed ran its window out reporting calm.
+ * Nothing threw. Passing it from the record the ADOPTION DECISION was made
+ * against removes the second read and keeps the thing probed the same thing
+ * that was adopted.
+ */
+export interface WatchSubject {
+    readonly workspace: string;
+    readonly pid: number;
+    /**
+     * F42: DOES THE CONTROL THIS WATCH WAS ATTACHED UNDER STILL HOLD — asked of
+     * the server before every walk. Present only for a watch attached to a
+     * CONTROLLED session; an observe-only watch has no grant to withdraw, so it
+     * has nothing to ask and the runtime's constant stands.
+     *
+     * 🔴 A LIVE RUN FOUND THE GAP. LIVE-3 revoked a controlled session's grant
+     * and the watch attached under it kept recording for its whole window, then
+     * closed as `expired` — "the grant ended at" a moment the grant never ended
+     * at. It rejects when the server cannot be asked, which the runtime already
+     * turns into a stop with that blind spot named in the record.
+     */
+    readonly stillAuthorized?: () => Promise<boolean>;
+}
+export declare const DEFAULT_WATCH_MINUTES = 30;
+export declare const MAX_WATCH_MINUTES: number;
+/** Events one watch may record before it stops and reports itself truncated. */
+export declare const WATCH_EVENT_CAP = 5000;
+export declare const EXIT_OK = 0;
+/**
+ * F41: THE LONGEST `--direct --wait` MAY ASK FOR, in seconds. The default wait stays short (bin.ts), because
+ * an unbounded wait is this process hanging on the cooperation of the thing it directs; but a session whose
+ * adapter runs a real provider turn answers in tens of seconds, not ten, and without a way to wait for it every
+ * permitted direction read as "no answer yet". MEASURED for LIVE-3. Asked for explicitly, and bounded.
+ */
+export declare const MAX_DIRECT_WAIT_S = 600;
+export declare const EXIT_USAGE = 2;
+export declare const EXIT_REFUSED = 3;
+/** Nothing was established. Distinct from refused, and a script must not read it as either. */
+export declare const EXIT_UNMEASURABLE = 4;
+export interface SessionsDeps {
+    /** Read and validate a claim file. `null` when it cannot be read or is not a claim. */
+    readClaim(path: string): Promise<SessionClaim | null>;
+    /** Everything this machine can establish on its own about that claim. */
+    measure(claim: SessionClaim, consent: {
+        authorized: boolean;
+        acked: boolean;
+    }): Promise<SessionMeasurements>;
+    records(): Promise<SessionRecord[]>;
+    /**
+     * What the SERVER says about directing this session.
+     *
+     * 🔴 THE ONLY SOURCE OF THE AUTHORIZATION HALF. `OWNER_CHARTER.md` §5 F-14:
+     * the machine cannot issue its own human grant, and a local file cannot hold
+     * server authority. So this asks the server, and the local record — which is
+     * a machine's own file — no longer feeds `authorized` at all.
+     *
+     * `null` when this machine is not paired or the server cannot be reached.
+     * That is NOT "no grant": it is "nothing was established", and it is reported
+     * as such rather than folded into a refusal.
+     */
+    serverControl?(sessionId: string): Promise<ControlVerdict | null>;
+    /**
+     * Attach a bounded watcher and run it to its end.
+     *
+     * 🔴 THE COMMAND DECIDES THE BOUNDS; THE RUNTIME ONLY WALKS. Every field
+     * of the window is a decision with a reason — which moment it covers from,
+     * which paths, how long, how many events — and deciding them here keeps them
+     * testable without a filesystem and keeps the walker from quietly acquiring
+     * an opinion about any of them.
+     *
+     * Absent when this build has no watcher. That is reported as nothing having
+     * been established, never as a session that was watched and was quiet.
+     */
+    watch?(window: WatchWindow, subject: WatchSubject): Promise<ObservationRecord>;
+    /**
+     * Everything needed to decide whether an instruction may be sent, in ONE read.
+     *
+     * 🔴 ONE READ, NOT THREE. The verdict, the scope and the expiry all come
+     * from the same grant, and fetching them separately opens a window where they
+     * describe different grants — which is how a caller ends up checking a verb
+     * against a scope that was superseded between the two calls. `mayDirect` is
+     * given a single coherent answer or none.
+     *
+     * `null` when nothing could be established, which is not a refusal.
+     */
+    directionContext?(sessionId: string): Promise<Omit<DirectionContext, 'at'> | null>;
+    /**
+     * Send one instruction and wait, within bounds, for the session's answer.
+     *
+     * 🔴 THE COMMAND DECIDES WHETHER IT MAY BE SENT; THIS ONLY SENDS IT.
+     * `mayDirect` has already answered before anything here runs.
+     *
+     * `null` when the session answered nothing inside the wait. ⚠️ THAT IS NOT
+     * A FAILURE OF THE INSTRUCTION — it is the absence of an answer, and the two
+     * read completely differently to whoever asked.
+     */
+    direct?(sessionId: string, instruction: Instruction, waitMs?: number): Promise<InstructionResult | null>;
+    /**
+     * Keep an observation where the process that made it cannot take it away.
+     *
+     * 🔴 CALLED TWICE FOR ONE WATCH: once before it begins and once when it
+     * closes. A record written only at the end exists only for watches that
+     * ENDED, and killing the process is the ordinary way a long watch stops — so
+     * the store would contain nothing, and nothing means "never watched". The
+     * same ambiguity `session-observe.ts` exists to destroy, reintroduced by the
+     * storage layer.
+     */
+    recordObservation?(record: ObservationRecord): Promise<void>;
+    /** What earlier watches recorded, as lines. */
+    observations?(sessionId: string): Promise<readonly string[]>;
+    /** What this machine can establish about a workspace, for a checkpoint. */
+    measureWorkspace?(workspace: string, sessionId: string, pid: number): Promise<CheckpointMeasurements>;
+    /**
+     * Write the checkpoint and its export.
+     *
+     * 🔴 IT WRITES; IT DOES NOT START ANYTHING. The charter's phrase is
+     * "checkpoint/export-and-new-managed-run", and a product that started the run
+     * itself would be adopting the work of a session it just refused to adopt EM
+     * the fake label arriving by the back door with a checkpoint as its receipt.
+     */
+    writeCheckpoint?(checkpoint: Checkpoint): Promise<readonly string[]>;
+    append(record: SessionRecord): Promise<void>;
+    now(): string;
+    newHandshakeId(): string;
+    out(line: string): void;
+    err(line: string): void;
+}
+export declare function sessionsCommand(argv: readonly string[], deps: SessionsDeps): Promise<number>;
+/**
+ * ⚠️ FOUR EXIT CODES, NOT THREE. `unmeasurable` gets its own, because a script
+ * that retried a refusal would be wrong and a script that ignored an
+ * unmeasurable would be worse — they are different instructions to the caller.
+ */
+export declare function verdictExit(v: SessionAdoptionVerdict): number;
+//# sourceMappingURL=sessions-cmd.d.ts.map

package/dist/sessions-cmd.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions-cmd.d.ts","sourceRoot":"","sources":["../src/sessions-cmd.ts"],"names":[],"mappings":"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"}