@hasna/hooks 0.10.8 → 0.11.0

package/dist/lib/codex-safety-check.d.ts

@@ -28,10 +28,11 @@ type NativeGuard = {
 };
 /** Select only the exact packaged composite definition in native discovery.
  * A name, a settings file, or a trusted hash by itself is not enough. */
-export declare function selectCodexSafety(discovery: unknown, configuration: unknown, home: string, cwd: string, featureEnabled?: boolean, requireReady?: boolean): NativeGuard;
+export declare function selectCodexSafety(discovery: unknown, configuration: unknown, home: string, cwd: string, featureEnabled?: boolean, requireReady?: boolean, readiness?: boolean): NativeGuard;
 export declare function readCodexSafety(rpc: CodexSafetyRpc, home: string, cwd: string, options?: {
     includeLayers?: boolean;
     requireReady?: boolean;
+    readiness?: boolean;
 }): Promise<{
     guard: NativeGuard;
     discovery: unknown;

package/dist/lib/codex-safety-trust.d.ts

@@ -9,9 +9,8 @@ interface Dependencies {
     connect?: typeof connectCodexSafety;
     verify?: typeof verifyNativeSafetyCommand;
 }
-type Options = CodexSafetyOptions;
 export interface CodexTrustPlan {
-    schema: "hasna.hooks.codex-safety-trust/v1";
+    schema: "hasna.hooks.codex-safety-trust/v1" | "hasna.hooks.codex-readiness-trust/v1";
     planDigest: string;
     nativeVersion: string;
     cwd: string;
@@ -20,24 +19,56 @@ export interface CodexTrustPlan {
     configPath: string;
     configVersion: string;
     action: "unchanged" | "trust_and_enable";
-    guardVerified: true;
+    guardVerified: boolean;
+    readinessRunnerVerified?: true;
     nativeAdoptionVerified: false;
 }
-export declare function planCodexSafetyTrust(options?: Options, dependencies?: Dependencies): Promise<CodexTrustPlan>;
-export declare function applyCodexSafetyTrust(options: Options & {
+export declare const planCodexSafetyTrust: (options?: CodexSafetyOptions, dependencies?: Dependencies) => Promise<CodexTrustPlan>;
+export declare const applyCodexSafetyTrust: (options: CodexSafetyOptions & {
     expectedPlanDigest: string;
-}, dependencies?: Dependencies): Promise<{
+}, dependencies?: Dependencies) => Promise<{
+    nativeDiscoveryVerified: boolean;
+    nativeAdoptionVerified: boolean;
+    unrelatedConfigurationPreserved: boolean;
+    readinessRunnerVerified?: boolean | undefined;
     ok: boolean;
     changed: boolean;
     operationId: string;
     planDigest: string;
     configVersion: any;
     guardVerified: boolean;
+} | {
+    schema: "hasna.hooks.codex-safety-trust/v1" | "hasna.hooks.codex-readiness-trust/v1";
+    planDigest: string;
+    nativeVersion: string;
+    cwd: string;
+    key: string;
+    currentHash: string;
+    configPath: string;
+    configVersion: string;
+    action: "unchanged" | "trust_and_enable";
+    guardVerified: boolean;
+    readinessRunnerVerified?: true;
+    nativeAdoptionVerified: false;
+    ok: boolean;
+    changed: boolean;
+}>;
+export declare const planCodexReadinessTrust: (options?: CodexSafetyOptions, dependencies?: Dependencies) => Promise<CodexTrustPlan>;
+export declare const applyCodexReadinessTrust: (options: CodexSafetyOptions & {
+    expectedPlanDigest: string;
+}, dependencies?: Dependencies) => Promise<{
     nativeDiscoveryVerified: boolean;
     nativeAdoptionVerified: boolean;
     unrelatedConfigurationPreserved: boolean;
+    readinessRunnerVerified?: boolean | undefined;
+    ok: boolean;
+    changed: boolean;
+    operationId: string;
+    planDigest: string;
+    configVersion: any;
+    guardVerified: boolean;
 } | {
-    schema: "hasna.hooks.codex-safety-trust/v1";
+    schema: "hasna.hooks.codex-safety-trust/v1" | "hasna.hooks.codex-readiness-trust/v1";
     planDigest: string;
     nativeVersion: string;
     cwd: string;
@@ -46,7 +77,8 @@ export declare function applyCodexSafetyTrust(options: Options & {
     configPath: string;
     configVersion: string;
     action: "unchanged" | "trust_and_enable";
-    guardVerified: true;
+    guardVerified: boolean;
+    readinessRunnerVerified?: true;
     nativeAdoptionVerified: false;
     ok: boolean;
     changed: boolean;

package/dist/lib/installer.d.ts

@@ -72,6 +72,17 @@ export declare function previewNativeSafetyRegistration(target: "codex" | "claud
     after: string;
     command: string;
 };
+/** Fixed bundled startup observer, rendered through the same native writer as
+ * safety hooks. The ready-plan binding is installed after native trust, since
+ * trusting Codex changes the configuration that the ready plan must capture. */
+export declare function previewNativeReadinessRegistration(target: "codex" | "claude"): {
+    before: string | null;
+    after: string;
+    command: string;
+};
+export declare function installNativeReadinessRegistration(target: "codex" | "claude", expectedSettingsSha256: string): {
+    success: boolean;
+};
 export declare function installHooks(names: string[], options?: InstallOptions): InstallResult[];
 export declare function getRegisteredHooksForTarget(scope?: Scope, target?: SingleTarget): string[];
 export declare function getRegisteredHooks(scope?: Scope): string[];

package/dist/lib/native-readiness-command.d.ts

@@ -0,0 +1,14 @@
+import { type ReadinessProvider } from "../native-readiness";
+interface CommandBinding {
+    provider: ReadinessProvider;
+    home: string;
+    runtime: string;
+    runtimeSHA256: string;
+    worker: string;
+    workerSHA256: string;
+}
+export declare function buildNativeReadinessCommand(binding: CommandBinding): string;
+export declare function nativeReadinessCommandBinding(command: string): CommandBinding | undefined;
+export declare function nativeReadinessCommandVerified(command: string): boolean;
+export declare function installedNativeReadinessCommand(provider: ReadinessProvider): string;
+export {};

package/dist/lib/native-safety-registration.d.ts

@@ -8,7 +8,7 @@ export interface NativeRegistrationOptions {
     target: "codex" | "claude";
 }
 export interface NativeRegistrationPlan {
-    schema: "hasna.hooks.native-safety-registration/v1";
+    schema: "hasna.hooks.native-safety-registration/v1" | "hasna.hooks.native-readiness-registration/v1";
     target: "codex" | "claude";
     settingsPath: string;
     resolvedPath: string;
@@ -17,25 +17,55 @@ export interface NativeRegistrationPlan {
     commandSHA256: string;
     action: "unchanged" | "register";
     planDigest: string;
-    guardVerified: true;
+    guardVerified: boolean;
+    readinessRunnerVerified?: true;
     nativeAdoptionVerified: false;
 }
 interface Dependencies {
     verify?: typeof verifyNativeSafetyCommand;
 }
-export declare function planNativeSafetyRegistration(options: NativeRegistrationOptions, dependencies?: Dependencies): Promise<NativeRegistrationPlan>;
-export declare function applyNativeSafetyRegistration(options: NativeRegistrationOptions & {
+export declare const planNativeSafetyRegistration: (options: NativeRegistrationOptions, dependencies?: Dependencies) => Promise<NativeRegistrationPlan>;
+export declare const applyNativeSafetyRegistration: (options: NativeRegistrationOptions & {
     expectedPlanDigest: string;
-}, dependencies?: Dependencies): Promise<{
+}, dependencies?: Dependencies) => Promise<{
+    nativeAdoptionVerified: boolean;
+    readinessRunnerVerified?: boolean | undefined;
     ok: boolean;
     changed: boolean;
     operationId: `${string}-${string}-${string}-${string}-${string}`;
     planDigest: string;
     settingsSHA256: string;
     guardVerified: boolean;
+} | {
+    schema: "hasna.hooks.native-safety-registration/v1" | "hasna.hooks.native-readiness-registration/v1";
+    target: "codex" | "claude";
+    settingsPath: string;
+    resolvedPath: string;
+    beforeSHA256: string;
+    desiredSHA256: string;
+    commandSHA256: string;
+    action: "unchanged" | "register";
+    planDigest: string;
+    guardVerified: boolean;
+    readinessRunnerVerified?: true;
+    nativeAdoptionVerified: false;
+    ok: boolean;
+    changed: boolean;
+}>;
+export declare const planNativeReadinessRegistration: (options: NativeRegistrationOptions) => Promise<NativeRegistrationPlan>;
+export declare const applyNativeReadinessRegistration: (options: NativeRegistrationOptions & {
+    expectedPlanDigest: string;
+}) => Promise<{
     nativeAdoptionVerified: boolean;
+    readinessRunnerVerified?: boolean | undefined;
+    ok: boolean;
+    changed: boolean;
+    operationId: `${string}-${string}-${string}-${string}-${string}`;
+    planDigest: string;
+    settingsSHA256: string;
+    guardVerified: boolean;
 } | {
-    schema: "hasna.hooks.native-safety-registration/v1";
+    schema: "hasna.hooks.native-safety-registration/v1" | "hasna.hooks.native-readiness-registration/v1";
     target: "codex" | "claude";
     settingsPath: string;
     resolvedPath: string;
@@ -44,7 +74,8 @@ export declare function applyNativeSafetyRegistration(options: NativeRegistratio
     commandSHA256: string;
     action: "unchanged" | "register";
     planDigest: string;
-    guardVerified: true;
+    guardVerified: boolean;
+    readinessRunnerVerified?: true;
     nativeAdoptionVerified: false;
     ok: boolean;
     changed: boolean;

package/dist/lib/readiness-process.d.ts

@@ -0,0 +1,20 @@
+export interface ReadinessChildResult {
+    status: number | null;
+    signal?: string | null;
+    error?: {
+        code?: string;
+    };
+    stdout: string;
+    stderr: string;
+}
+export interface ReadinessProcessOptions {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    timeout: number;
+    maxBuffer: number;
+    signal?: AbortSignal;
+}
+/** Bound the whole freshly spawned read-only check tree, including nested
+ * Instructions/Hooks clients. Async execution keeps a shared harness responsive.
+ * Even a successful check is cleaned up before its result is returned. */
+export declare function runReadinessProcess(command: string, args: string[], options: ReadinessProcessOptions): Promise<ReadinessChildResult>;

package/dist/native-readiness.d.ts

@@ -0,0 +1,68 @@
+import { type ReadinessChildResult, type ReadinessProcessOptions } from "./lib/readiness-process";
+export type ReadinessProvider = "claude" | "codex" | "sumi";
+type Pin = {
+    path: string;
+    sha256: string;
+};
+export interface TrashReadinessBinding {
+    schema: "hasna.hooks.trash-readiness/v1";
+    provider: ReadinessProvider;
+    home: string;
+    runtime: Pin;
+    trash: {
+        root: string;
+        version: string;
+        cliSha256: string;
+    };
+    plan: Pin;
+    timeoutMs: number;
+}
+export type ReadinessCode = "ready" | "binding_missing" | "binding_invalid" | "unsafe_path" | "file_changed" | "package_mismatch" | "plan_invalid" | "deadline_exceeded" | "execution_failed" | "output_invalid" | "unsupported_platform" | "station_detection_failed" | "station_mismatch" | "retention_mismatch" | "hosted_unavailable" | "authentication_refused" | "station_setup_required" | "invalid_status" | "managed_instructions_refused" | "removal_instruction_missing" | "native_config_changed" | "instructions_changed" | "guard_refused" | "owner_refused" | "check_failed" | "input_invalid";
+export interface TrashReadinessResult {
+    schema: "hasna.hooks.trash-readiness-result/v1";
+    provider: ReadinessProvider;
+    ready: boolean;
+    code: ReadinessCode;
+    station?: string;
+    planDigest?: string;
+    nativeAdoptionVerified: false;
+}
+export declare function isReadinessProvider(value: unknown): value is ReadinessProvider;
+export declare function parseTrashReadinessBinding(input: unknown, provider: ReadinessProvider, home: string): TrashReadinessBinding;
+export declare function trashReadinessBindingPath(provider: ReadinessProvider, home?: string): string;
+/** Opening a pipe must never delay the startup check. Read canonical regular
+ * files only, with safe owner/root ancestry and bounded bytes. */
+declare function readSafe(path: string, maximum: number, executable?: boolean): Buffer;
+/** Fixed-schema operator input; never a credential or a free-form command. */
+export declare function readTrashReadinessBindingFile(path: string, provider: ReadinessProvider, home?: string): {
+    binding: TrashReadinessBinding;
+    raw: Buffer<ArrayBufferLike>;
+    sha256: string;
+};
+interface Dependencies {
+    home?: string;
+    read?: typeof readSafe;
+    signal?: AbortSignal;
+    spawn?: (runtime: string, args: string[], options: ReadinessProcessOptions) => ReadinessChildResult | Promise<ReadinessChildResult>;
+}
+/** Executes only the selected installed Trash CLI's read-only check. Never
+ * forwards either stream: provider bodies and unrelated diagnostics stay out
+ * of the native prompt. No retry, repair, binding write or removal occurs. */
+export declare function runTrashReadiness(provider: ReadinessProvider, d?: Dependencies): Promise<TrashReadinessResult>;
+/** Check a proposed binding without installing it. This shares the exact
+ * runtime check; only the not-yet-written fixed binding file is supplied from
+ * the captured input. Every artifact, plan and service read remains real. */
+export declare function checkTrashReadinessBinding(input: TrashReadinessBinding): Promise<TrashReadinessResult>;
+/** SessionStart is observational, not a removal authorization. A failed check
+ * stays an explicit attention diagnostic; the removal guard remains separate. */
+export declare function readinessContext(result: TrashReadinessResult): string;
+export declare function readinessSessionStartOutput(result: TrashReadinessResult): {
+    hookSpecificOutput: {
+        hookEventName: string;
+        additionalContext: string;
+    };
+};
+/** Session payloads are untrusted data. Read only the documented event/source;
+ * never follow transcript paths, forward prompt text or run on tool events. */
+export declare function handleReadinessSessionStart(provider: ReadinessProvider, event: unknown, dependencies?: Dependencies): Promise<{}>;
+export {};

package/dist/native-readiness.js

@@ -0,0 +1,328 @@
+// @bun
+// src/native-readiness.ts
+import { createHash } from "crypto";
+
+// src/lib/readiness-process.ts
+import { spawn } from "child_process";
+var supervisor = String.raw`
+  const {spawn}=require("node:child_process");
+  const spec=JSON.parse(process.argv.at(-1));
+  // This runtime was created detached and is its group's live leader. Its
+  // independent timer and parent pipe remain effective if the observer exits
+  // or its event loop stops responding. Only this freshly created tree is hit.
+  const cleanup=()=>{try{process.kill(-process.pid,"SIGKILL")}catch{process.exit(1)}};
+  setTimeout(cleanup,spec.timeout);
+  process.stdin.once("end",cleanup);
+  process.stdin.once("error",cleanup);
+  process.stdin.on("data",cleanup);
+  process.stdin.resume();
+  for(const signal of ["SIGTERM","SIGINT","SIGHUP"])process.once(signal,cleanup);
+  let done=false, out=Buffer.alloc(0), err=Buffer.alloc(0);
+  function report(status,error){
+    if(done)return; done=true;
+    process.stdout.write(JSON.stringify({status,error,stdout:out.toString("utf8"),stderr:err.toString("utf8")})+"\n");
+  }
+  const child=spawn(spec.command,spec.args,{stdio:["ignore","pipe","pipe"],env:process.env});
+  for(const [stream,name] of [[child.stdout,"stdout"],[child.stderr,"stderr"]]){
+    stream.on("data",bytes=>{
+      if(done)return;
+      const before=name==="stdout"?out:err;
+      if(before.length+bytes.length>spec.maxBuffer){report(null,{code:"ENOBUFS"});return}
+      if(name==="stdout")out=Buffer.concat([out,bytes]);else err=Buffer.concat([err,bytes]);
+    });
+    stream.on("error",()=>report(null,{code:"ECHILD"}));
+  }
+  child.on("error",()=>report(null,{code:"ECHILD"}));
+  // A successful observation includes complete streams. A nested client that
+  // keeps them open after its parent exits is a failure requiring group cleanup.
+  child.on("exit",()=>setTimeout(()=>report(null,{code:"ECHILD"}),100));
+  child.on("close",(status,signal)=>report(status,signal?{code:"ECHILD"}:undefined));
+`;
+function runReadinessProcess(command, args, options) {
+  if (!["darwin", "linux"].includes(process.platform)) {
+    return Promise.resolve({ status: null, error: { code: "ENOTSUP" }, stdout: "", stderr: "" });
+  }
+  if (options.signal?.aborted) {
+    return Promise.resolve({ status: null, error: { code: "ABORT_ERR" }, stdout: "", stderr: "" });
+  }
+  return new Promise((resolve) => {
+    const child = spawn(command, ["--config=/dev/null", "--no-env-file", "--no-macros", "--no-install", "--eval", supervisor, "--", JSON.stringify({ command, args, maxBuffer: options.maxBuffer, timeout: options.timeout })], {
+      cwd: options.cwd,
+      env: options.env,
+      detached: true,
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    let status = null, error;
+    let stopping = false, exited = false, finished = false;
+    let stdout = "", stderr = "", control = "";
+    const maximumEnvelope = options.maxBuffer * 12 + 1024;
+    let cleanup;
+    const finish = () => {
+      if (finished)
+        return;
+      finished = true;
+      clearTimeout(deadline);
+      clearTimeout(cleanup);
+      options.signal?.removeEventListener("abort", abort);
+      child.stdin?.destroy();
+      child.stdout?.destroy();
+      child.stderr?.destroy();
+      resolve({ status, error, stdout, stderr });
+    };
+    const stop = (code) => {
+      if (code && !finished)
+        error ??= { code };
+      if (finished || stopping)
+        return;
+      stopping = true;
+      if (exited || !child.pid) {
+        error ??= { code: "ECHILD" };
+      } else {
+        try {
+          child.stdin.end();
+        } catch {
+          error = { code: "ECHILD" };
+        }
+      }
+      cleanup = setTimeout(() => {
+        error = { code: "ECHILD" };
+        finish();
+      }, 1000);
+    };
+    const abort = () => stop("ABORT_ERR");
+    const deadline = setTimeout(() => stop("ETIMEDOUT"), options.timeout);
+    options.signal?.addEventListener("abort", abort, { once: true });
+    if (options.signal?.aborted)
+      abort();
+    child.stdin?.on("error", () => {
+      if (!stopping)
+        stop("ECHILD");
+    });
+    child.stdout?.on("data", (bytes) => {
+      if (stopping)
+        return;
+      control += bytes.toString("utf8");
+      if (Buffer.byteLength(control) > maximumEnvelope)
+        return stop("ENOBUFS");
+      if (!control.endsWith(`
+`))
+        return;
+      try {
+        const value = JSON.parse(control);
+        if (!value || typeof value !== "object" || Array.isArray(value) || Object.keys(value).some((key) => !["status", "error", "stdout", "stderr"].includes(key)) || !(value.status === null || Number.isInteger(value.status) && value.status >= 0 && value.status <= 255) || typeof value.stdout !== "string" || typeof value.stderr !== "string" || Buffer.byteLength(value.stdout) > options.maxBuffer || Buffer.byteLength(value.stderr) > options.maxBuffer || value.error !== undefined && (Object.keys(value.error).join() !== "code" || !["ENOBUFS", "ECHILD"].includes(value.error.code))) {
+          return stop("EPROTO");
+        }
+        status = value.status;
+        stdout = value.stdout;
+        stderr = value.stderr;
+        stop(value.error?.code);
+      } catch {
+        stop("EPROTO");
+      }
+    });
+    child.stdout?.on("error", () => stop("EPROTO"));
+    child.stderr?.on("data", () => stop("ECHILD"));
+    child.stderr?.on("error", () => stop("ECHILD"));
+    child.on("error", () => {
+      error = { code: "ECHILD" };
+      stop();
+    });
+    child.on("exit", () => {
+      exited = true;
+      if (!stopping)
+        stop("ECHILD");
+    });
+    child.on("close", () => {
+      if (!stopping)
+        error = { code: "ECHILD" };
+      finish();
+    });
+  });
+}
+
+// src/native-readiness.ts
+import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, realpathSync } from "fs";
+import { homedir } from "os";
+import { dirname, isAbsolute, join, relative, resolve } from "path";
+
+class ReadinessError extends Error {
+  code;
+  constructor(code) {
+    super(code);
+    this.code = code;
+  }
+}
+function need(value, code) {
+  if (!value)
+    throw new ReadinessError(code);
+}
+var sha = (value) => createHash("sha256").update(value).digest("hex");
+var digest = (v) => typeof v === "string" && /^[a-f0-9]{64}$/.test(v);
+var absolute = (v) => typeof v === "string" && v.length <= 4096 && isAbsolute(v) && resolve(v) === v && !/[\0\r\n]/.test(v);
+var object = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+var keys = (v, expected) => object(v) && Object.keys(v).sort().join() === expected.sort().join();
+var pin = (v) => keys(v, ["path", "sha256"]) && absolute(v.path) && digest(v.sha256);
+function isReadinessProvider(value) {
+  return value === "claude" || value === "codex" || value === "sumi";
+}
+function inside(home, path) {
+  const part = relative(home, path);
+  return part !== "" && part !== ".." && !part.startsWith("../") && !isAbsolute(part);
+}
+function parseTrashReadinessBinding(input, provider, home) {
+  const b = input;
+  need(isReadinessProvider(provider) && absolute(home), "binding_invalid");
+  need(keys(b, ["schema", "provider", "home", "runtime", "trash", "plan", "timeoutMs"]) && b.schema === "hasna.hooks.trash-readiness/v1" && b.provider === provider && b.home === home && pin(b.runtime) && pin(b.plan) && keys(b.trash, ["root", "version", "cliSha256"]) && absolute(b.trash.root) && typeof b.trash.version === "string" && b.trash.version.length <= 128 && /^\d+\.\d+\.\d+$/.test(b.trash.version) && digest(b.trash.cliSha256) && Number.isInteger(b.timeoutMs) && b.timeoutMs >= 1000 && b.timeoutMs <= 15000 && inside(home, b.plan.path) && inside(home, b.trash.root), "binding_invalid");
+  return structuredClone(b);
+}
+function trashReadinessBindingPath(provider, home = homedir()) {
+  need(isReadinessProvider(provider) && absolute(home), "binding_invalid");
+  return join(home, ".hasna", "hooks", "native", "trash-readiness", provider + ".json");
+}
+function readSafe(path, maximum, executable = false) {
+  need(absolute(path) && realpathSync(path) === path, "unsafe_path");
+  for (let parent = dirname(path);; parent = dirname(parent)) {
+    const stat = lstatSync(parent);
+    need(stat.isDirectory() && [0, process.getuid?.()].includes(stat.uid) && !(stat.mode & 18), "unsafe_path");
+    if (parent === dirname(parent))
+      break;
+  }
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const stat = fstatSync(fd);
+    need(stat.isFile() && [0, process.getuid?.()].includes(stat.uid) && !(stat.mode & 18) && stat.size <= maximum && (!executable || !!(stat.mode & 64)), "unsafe_path");
+    const bytes = Buffer.alloc(stat.size + 1);
+    let length = 0;
+    while (length < bytes.length) {
+      const count = readSync(fd, bytes, length, bytes.length - length, null);
+      if (!count)
+        break;
+      length += count;
+    }
+    const after = fstatSync(fd);
+    need(length === stat.size && after.size === stat.size && after.mtimeMs === stat.mtimeMs && after.ctimeMs === stat.ctimeMs, "file_changed");
+    return bytes.subarray(0, length);
+  } finally {
+    closeSync(fd);
+  }
+}
+function readTrashReadinessBindingFile(path, provider, home = realpathSync(homedir())) {
+  const raw = readSafe(path, 65536);
+  return { binding: parseTrashReadinessBinding(JSON.parse(raw.toString("utf8")), provider, home), raw, sha256: sha(raw) };
+}
+var safeFailureCodes = new Set([
+  "unsupported_platform",
+  "station_detection_failed",
+  "station_mismatch",
+  "hosted_unavailable",
+  "authentication_refused",
+  "station_setup_required",
+  "invalid_status",
+  "deadline_exceeded",
+  "retention_mismatch",
+  "managed_instructions_refused",
+  "removal_instruction_missing",
+  "instructions_changed",
+  "native_config_changed",
+  "guard_refused",
+  "owner_refused"
+]);
+async function runTrashReadiness(provider, d = {}) {
+  const started = performance.now();
+  const result = (code, extra = {}) => ({
+    schema: "hasna.hooks.trash-readiness-result/v1",
+    provider,
+    ready: code === "ready",
+    code,
+    nativeAdoptionVerified: false,
+    ...extra
+  });
+  let phase = "binding";
+  try {
+    const home = d.home ?? realpathSync(homedir()), read = d.read ?? readSafe;
+    need(isReadinessProvider(provider), "binding_invalid");
+    const bindingPath = trashReadinessBindingPath(provider, home), bindingBytes = read(bindingPath, 65536);
+    const b = parseTrashReadinessBinding(JSON.parse(bindingBytes.toString("utf8")), provider, home);
+    phase = "consumer";
+    const checkPin = (p, maximum, executable = false) => {
+      const bytes = read(p.path, maximum, executable);
+      need(sha(bytes) === p.sha256, "file_changed");
+      return bytes;
+    };
+    checkPin(b.runtime, 200000000, true);
+    const manifestPath = join(b.trash.root, "package.json"), manifestBytes = read(manifestPath, 65536);
+    const manifest = JSON.parse(manifestBytes.toString("utf8"));
+    need(manifest.name === "@hasna/trash" && manifest.version === b.trash.version && manifest.bin?.trash === "dist/cli/index.js", "package_mismatch");
+    const cli = join(b.trash.root, "dist", "cli", "index.js");
+    checkPin({ path: cli, sha256: b.trash.cliSha256 }, 64 * 1024 * 1024, true);
+    const plan = JSON.parse(checkPin(b.plan, 65536).toString("utf8"));
+    need(plan?.schema === "hasna.trash.station-setup-plan/v1" && plan.stage === "ready" && plan.configurationReady === true && plan.nativeAdoptionVerified === false && digest(plan.planDigest) && plan.spec?.provider === provider && plan.spec.home === home && typeof plan.spec.station === "string" && /^[a-z0-9][a-z0-9-]{0,62}$/.test(plan.spec.station) && plan.spec.runtime?.path === b.runtime.path && plan.spec.runtime?.sha256 === b.runtime.sha256 && absolute(plan.spec.cwd) && (plan.spec.cwd === home || inside(home, plan.spec.cwd)) && typeof plan.spec.path === "string" && plan.spec.path.length <= 8192 && plan.spec.path.split(":").every(absolute), "plan_invalid");
+    const args = ["--config=/dev/null", "--no-env-file", "--no-macros", "--no-install", cli, "station", "check", "--plan", b.plan.path];
+    const remaining = () => Math.floor(b.timeoutMs - (performance.now() - started));
+    const timeout = remaining();
+    need(timeout > 0, "deadline_exceeded");
+    const child = await (d.spawn ?? runReadinessProcess)(b.runtime.path, args, {
+      cwd: home,
+      env: { HOME: home, PATH: plan.spec.path, LANG: "C", NO_COLOR: "1" },
+      timeout,
+      maxBuffer: 16384,
+      signal: d.signal
+    });
+    need(remaining() > 0, "deadline_exceeded");
+    if (child.error && "code" in child.error && child.error.code === "ETIMEDOUT")
+      return result("deadline_exceeded");
+    if (child.error || child.signal || child.status === null)
+      return result("execution_failed");
+    need(typeof child.stdout === "string" && typeof child.stderr === "string" && Buffer.byteLength(child.stdout) <= 16384 && Buffer.byteLength(child.stderr) <= 16384, "output_invalid");
+    let value;
+    try {
+      value = JSON.parse(child.stdout);
+    } catch {
+      return result("output_invalid");
+    }
+    if (child.status !== 0 || value?.configurationReady !== true) {
+      return result(safeFailureCodes.has(value?.code) ? value.code : "check_failed");
+    }
+    need(value.schema === "hasna.trash.station-setup-result/v1" && value.station === plan.spec.station && value.provider === provider && value.planDigest === plan.planDigest && value.serviceReady === true && value.guardVerified === true && value.managedInstructionsVerified === true && value.mcpConfigurationVerified === true && value.mcpExecutionVerified === false && value.nativeAdoptionVerified === false && child.stderr.length === 0, "output_invalid");
+    checkPin(b.plan, 65536);
+    checkPin({ path: cli, sha256: b.trash.cliSha256 }, 64 * 1024 * 1024, true);
+    checkPin(b.runtime, 200000000, true);
+    need(read(bindingPath, 65536).equals(bindingBytes) && read(manifestPath, 65536).equals(manifestBytes), "file_changed");
+    need(remaining() > 0, "deadline_exceeded");
+    return result("ready", { station: value.station, planDigest: value.planDigest });
+  } catch (error) {
+    return result(error instanceof ReadinessError ? error.code : phase === "binding" && error?.code === "ENOENT" ? "binding_missing" : "binding_invalid");
+  }
+}
+function checkTrashReadinessBinding(input) {
+  const home = realpathSync(homedir()), b = parseTrashReadinessBinding(input, input?.provider, home);
+  const path = trashReadinessBindingPath(b.provider, home), raw = Buffer.from(JSON.stringify(b) + `
+`);
+  return runTrashReadiness(b.provider, { home, read: (selected, maximum, executable) => selected === path ? raw : readSafe(selected, maximum, executable) });
+}
+function readinessContext(result) {
+  return result.ready ? `Trash readiness verified for ${result.station} (${result.provider}). Use Trash for recoverable file removal.` : `Trash readiness needs attention (${result.provider}: ${result.code}). Preserve files; do not fall back to direct deletion. Refresh the station setup before removal.`;
+}
+function readinessSessionStartOutput(result) {
+  return { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: readinessContext(result) } };
+}
+async function handleReadinessSessionStart(provider, event, dependencies = {}) {
+  const input = event;
+  if (!object(input) || input.hook_event_name !== "SessionStart" || !["startup", "resume", "clear", "fork", "compact"].includes(input.source)) {
+    return readinessSessionStartOutput({ schema: "hasna.hooks.trash-readiness-result/v1", provider, ready: false, code: "input_invalid", nativeAdoptionVerified: false });
+  }
+  if (input.source === "compact")
+    return {};
+  return readinessSessionStartOutput(await runTrashReadiness(provider, dependencies));
+}
+export {
+  trashReadinessBindingPath,
+  runTrashReadiness,
+  readinessSessionStartOutput,
+  readinessContext,
+  readTrashReadinessBindingFile,
+  parseTrashReadinessBinding,
+  isReadinessProvider,
+  handleReadinessSessionStart,
+  checkTrashReadinessBinding
+};

package/hooks/hook-workspace-repos-guard/README.md

@@ -51,8 +51,11 @@ word of a later read-only stage (`| head -60`) is never taken as the write
 target of an earlier stage. Pipes inside quotes or command substitutions are
 not stage boundaries.
 A protected path named anywhere in a pipeline takes the strongest operation
-of any stage (`find <root>/x | xargs rm -rf` is a delete). Deletes and
-`mkdir`/`touch` check every operand; other writers check their last one.
+of any stage (`find <root>/x | xargs rm -rf` is a delete). Deletes,
+`mkdir`/`touch`, `tee`, `truncate`, `install`, `mv` and `sed -i` check every
+operand (options end at `--` or at the first operand); other writers check
+their last one, plus any `-t`/`--target-directory` value. A delete tool's
+subcommand word is not an operand (`trash put <path>`, `git rm <path>`).
 An operand or redirect target that cannot be read statically (a variable
 other than `$HOME`, `$( )`, backticks, a glob) fails closed to the directory
 the command runs in, so `rm -rf "$TMPDIR/x"` run from a protected checkout is