toolroll 0.9.104 → 0.9.105

package/dist/containment.d.ts

@@ -1,205 +0,0 @@
-/**
- * OS process containment (docs/PROCESS_CONTAINMENT_PLAN.md).
- *
- * The stop contract before this module was OBSERVATIONAL: a provider's
- * tree is scanned every 500 ms, and a double fork can reparent between
- * scans. This module adds an OS boundary where the OS has one, and says
- * exactly what it has where it has none:
- *
- *   linux   a delegated cgroup v2 directory per spawn. The target is
- *           placed in it BEFORE it executes (the `sh` prelude below writes
- *           its own pid, then execs the target with argv verbatim), so a
- *           setsid/double-fork helper is born inside and dies with
- *           `cgroup.kill`. Emptiness is the kernel's own `cgroup.events`
- *           populated flag — never a transport exit. A detached janitor
- *           kills the cgroup when this worker dies.
- *   win32   a Job Object with kill-on-close and no breakaway, owned by a
- *           PowerShell helper OUTSIDE the job that creates the target
- *           suspended, assigns it, then resumes it. The helper's death —
- *           including this worker's death, which closes its stdin — closes
- *           the handle and the job kills everything in it.
- *   darwin  nothing. There is no supported cgroup/Job Object equivalent;
- *           NOTE_TRACK/NOTE_CHILD have been unsupported since 10.5 and
- *           launchd's AbandonProcessGroup only covers a process group. The
- *           observational mode stays, is reported as exactly that, and a
- *           REQUIRED policy refuses before any target executes.
- *
- * Three policies: `observed` (the behaviour every existing installation
- * has), `preferred` (native when this machine can, observed — and said
- * so — when it cannot), `required` (native or a refusal; never a silent
- * downgrade). The policy is decided ONCE per controller process from the
- * operator's flag or environment and pinned; nothing a child supplies and
- * no corrupt value can weaken a pinned requirement.
- */
-import { type ChildProcess } from "node:child_process";
-export declare const CONTAINMENT_POLICIES: readonly ["observed", "preferred", "required"];
-export type ContainmentPolicy = (typeof CONTAINMENT_POLICIES)[number];
-export type ContainmentBackendId = "cgroup2" | "job-object";
-/** The environment name the controller reads when no flag names a policy. */
-export declare const CONTAINMENT_ENV = "TOOLROLL_CONTAINMENT";
-export type PolicyParse = {
-    ok: true;
-    policy: ContainmentPolicy;
-    source: "default" | "explicit";
-} | {
-    ok: false;
-    problem: string;
-};
-/**
- * Parse an operator's policy word. Absent means `observed` — every
- * existing installation keeps its behaviour. Anything present must be
- * one of the three words exactly: a corrupt value is a refusal, never a
- * quiet fall back to observed (which would turn a requirement off).
- */
-export declare function parseContainmentPolicy(raw: string | undefined | null): PolicyParse;
-export type ContainmentCapability = {
-    platform: NodeJS.Platform;
-    backend: ContainmentBackendId | null;
-    available: boolean;
-    /** Why, in words an operator can act on. */
-    detail: string;
-    /** cgroup2: the delegated cgroup directory this process may create children in. */
-    cgroupRoot?: string;
-    /** cgroup2: whether the kernel offers the required atomic cgroup.kill (5.14+). */
-    cgroupKill?: boolean;
-    /** job-object: the helper and the shell that runs it. */
-    helper?: string;
-    powershell?: string;
-};
-export type CapabilityProbeOptions = {
-    platform?: NodeJS.Platform;
-    /** Tests: the mounted cgroup2 root (default /sys/fs/cgroup). */
-    cgroupMount?: string;
-    /** Tests: this process's /proc/self/cgroup text. */
-    selfCgroup?: string;
-    /** Tests: where the Windows helper would be. */
-    helperPath?: string;
-    /** Tests: the PowerShell executable. */
-    powershellPath?: string;
-};
-/** The cgroup path of this process from /proc/self/cgroup (`0::/path`). */
-export declare function ownCgroupPath(selfCgroup: string): string | null;
-/**
- * What this machine can do, established by DOING it: on Linux, a child
- * cgroup is created and removed inside this process's own cgroup; a
- * mount that is not v2, a cgroup that is not delegated to this user, or
- * an unreadable /proc all answer unavailable with the reason. Nothing
- * here can be overridden by an environment variable into a claim the OS
- * did not make.
- */
-export declare function probeContainmentCapability(options?: CapabilityProbeOptions): ContainmentCapability;
-export declare function jobObjectHelperPath(): string;
-export type EffectiveContainment = {
-    policy: ContainmentPolicy;
-    capability: ContainmentCapability;
-    /** What spawns actually get. */
-    mode: "observed" | "native";
-    /** `preferred` on a machine that cannot: observed, and reported. */
-    downgraded: boolean;
-    /** `required` on a machine that cannot: every containable spawn refuses with these words, before any target executes. */
-    refusal: string | null;
-};
-/** The truthful composition of what was asked and what the OS offers. */
-export declare function effectiveContainment(policy: ContainmentPolicy, capability: ContainmentCapability): EffectiveContainment;
-/** One-line status words for `daemon status`, `up`, and the certificate. */
-export declare function describeContainment(effective: EffectiveContainment): string;
-/** The one sentence a person reads at start when agents on Linux run
- * without native containment that the machine could offer once set up;
- * null when there is nothing a person needs to read. The exact
- * `describeContainment` line stays in --verbose and in a service log. */
-export declare function containmentNotice(effective: EffectiveContainment): string | null;
-/** The status envelope's shape: no paths a person did not already know, no secrets. */
-export declare function containmentStatus(effective: EffectiveContainment): Record<string, unknown>;
-/**
- * Pin this process's containment ONCE, from the operator's own word. A
- * second pin may only tighten: once `required` stands nothing pins it
- * weaker — the only way down is a new process started with a new word.
- */
-export declare function pinContainment(effective: EffectiveContainment): EffectiveContainment;
-/**
- * Resolve the policy from a flag word, then the environment, then the
- * default, and pin it. A corrupt word is a refusal to start, never a
- * default: the caller reports `problem` and exits.
- */
-export declare function resolveContainment(flagWord: string | undefined, env?: NodeJS.ProcessEnv): {
-    ok: true;
-    effective: EffectiveContainment;
-} | {
-    ok: false;
-    problem: string;
-};
-/** What every containable spawn consults. Unpinned = observed, exactly as before this module. */
-export declare function currentContainment(): EffectiveContainment;
-/** Tests only. */
-export declare function resetContainmentForTests(): void;
-export type AttachOutcome = {
-    ok: true;
-} | {
-    ok: false;
-    detail: string;
-};
-/** How to spawn so the target is inside the OS object before it executes. */
-export type ContainedLaunch = {
-    file: string;
-    args: string[];
-    /** Extra stdio slots after stdin/stdout/stderr (the cgroup2 prelude confirms on fd 3). */
-    extraStdio: ("pipe" | "ignore")[];
-    /** Settles once the prelude has joined (before the target exec) or has failed (the target never ran). */
-    attach(child: ChildProcess): Promise<AttachOutcome>;
-};
-export type Container = {
-    backend: ContainmentBackendId;
-    /** The exact-run custody handle: cgroup directory or job name. */
-    id: string;
-    /** Kernel namespace/mount provenance for read-only recovery. */
-    identity?: string;
-    launch(file: string, args: readonly string[]): ContainedLaunch;
-    /** SIGKILL every member and wait for the OS to report the object empty. */
-    kill(timeoutMs?: number): Promise<boolean>;
-    /** true = members remain; false = proven empty; null = cannot be established right now. */
-    populated(): boolean | null;
-    waitEmpty(timeoutMs: number): Promise<boolean>;
-    /** Remove the OS object (only an empty one can go) and dismiss the janitor. */
-    release(): void;
-    /** Hard limits on the whole object, set before `launch`; false when this object can't enforce them. */
-    limit?(limits: {
-        memoryBytes: number;
-        pids: number;
-    }): boolean;
-};
-export type ContainerFactory = (effective: EffectiveContainment, label: string) => Container;
-/** Tests: substitute the OS object (a scripted or file-backed stand-in). */
-export declare function overrideContainerFactoryForTests(factory: ContainerFactory | null): void;
-/**
- * Make the OS object for one spawn, or say why not. `null` when the
- * effective mode is observed; a `refused` when native containment was
- * demanded and this spawn cannot have it — the caller must not spawn.
- */
-export declare function createContainer(effective: EffectiveContainment, label: string): {
-    container: Container;
-} | {
-    container: null;
-} | {
-    refused: string;
-};
-/**
- * The cgroup2 prelude: join, confirm on fd 3, close it, exec the target
- * with argv exactly as given (positional parameters, never re-parsed).
- * A join that fails exits 126 before the target can run.
- */
-export declare const CGROUP2_PRELUDE = "echo \"$$\" > \"$1/cgroup.procs\" || exit 126\nprintf \"attached\\n\" >&3 || exit 126\nIFS= read -r permit <&3 || exit 126\n[ \"$permit\" = go ] || exit 126\nexec 3>&-\nshift\nexec \"$@\"";
-/** The janitor: waits for this worker's pipe to close, then kills and removes the cgroup. */
-export declare const CGROUP2_JANITOR: string;
-export declare function safeContainerLabel(label: string): string;
-/** A cgroup v2 leaf under the delegated root. Exported for the native test's direct use. */
-export declare function cgroup2Container(capability: ContainmentCapability, label: string, mountOverride?: string): Container;
-/**
- * A Windows Job Object owned by a PowerShell helper outside the job. The
- * helper connects to a named pipe this process listens on and reports
- * `attached` only after CreateProcess(CREATE_SUSPENDED) + AssignProcess
- * ToJobObject + ResumeThread; `failed <detail>` means the target never
- * ran. `kill` asks for TerminateJobObject over the same pipe and waits
- * for the helper's `empty` reply. Physical Windows is where this runs;
- * the CI windows job exercises it.
- */
-export declare function jobObjectContainer(capability: ContainmentCapability, label: string): Container;

package/dist/contract-changes.d.ts

@@ -1,52 +0,0 @@
-/**
- * The mechanical difference between two sets of contract terms — a task's goal, exclusions, touches and acceptance
- * rubric. Pure and import-light, so both the planner's source (planner-source.ts) and scope filing (scope.ts, which
- * restarts planning when the terms truly change) read the same comparison.
- */
-import type { AcceptanceCriterion, EvidenceKind } from "./scope.js";
-/** The four contract fields a planner may propose to amend. */
-export type ContractTerms = {
-    goal: string;
-    outOfScope: string | null;
-    touches: string[];
-    acceptance: AcceptanceCriterion[];
-};
-export type ContractChange = {
-    field: "goal";
-    kind: "changed";
-    before: string;
-    after: string;
-} | {
-    field: "outOfScope";
-    kind: "added" | "removed" | "changed";
-    before: string | null;
-    after: string | null;
-} | {
-    field: "touches";
-    kind: "added" | "removed";
-    path: string;
-} | {
-    field: "acceptance";
-    kind: "added" | "removed" | "changed";
-    id: string;
-    before: {
-        statement: string;
-        evidence: EvidenceKind[];
-        how: string | null;
-    } | null;
-    after: {
-        statement: string;
-        evidence: EvidenceKind[];
-        how: string | null;
-    } | null;
-    /** For `changed`: which parts moved. `how` is advisory and unsigned,
-     * but a planner rewriting it is still a change the operator sees. */
-    moved: ("statement" | "evidence" | "how")[];
-};
-/**
- * Every addition, change, and removal between the filed contract and a
- * proposed one. Whitespace at the ends and touch/evidence order do not
- * count (the scope digest ignores them too); everything else does,
- * including the advisory `how`, because the operator wrote it.
- */
-export declare function contractChangesOf(filed: ContractTerms, proposed: ContractTerms): ContractChange[];

package/dist/contracts/acceptance-terms.d.ts

@@ -1,14 +0,0 @@
-/**
- * The acceptance rubric's vocabulary and limits: the evidence kinds a criterion may require, and how many criteria
- * and bytes a rubric may hold. A leaf with no imports but TEXT_LIMITS, because the plan contract (src/contracts/plan.ts)
- * reads these through scope.ts while scope.ts reads the plan contract's criterion: kept here, both load in either order.
- */
-export declare const EVIDENCE_KINDS: readonly ["check", "screenshot", "changed-path", "manual-review"];
-export type EvidenceKind = (typeof EVIDENCE_KINDS)[number];
-export declare const ACCEPTANCE_LIMITS: {
-    readonly criteria: 12;
-    readonly id: 40;
-    readonly statement: 1000;
-    readonly how: 500;
-    readonly evidenceKinds: 4;
-};