@hasna/skills 0.1.62 → 0.1.63

package/dist/server/types.d.ts

@@ -0,0 +1,242 @@
+import type { OwnedBytes } from "../lib/skill-bundle.js";
+export declare const SERVER_RUN_STATUSES: readonly ["queued", "waiting_for_approval", "running", "succeeded", "failed", "cancel_requested", "cancelled", "retrying", "expired", "refunded"];
+export type ServerRunStatus = (typeof SERVER_RUN_STATUSES)[number];
+/**
+ * A fenced transition was refused because the run's lease_generation moved on.
+ *
+ * The worker that throws this is writing against a run it no longer owns: a
+ * newer claim took it, or a cancellation fenced it. The run is not missing -
+ * that is the null return - it has simply left the writer behind.
+ */
+export declare class StaleLeaseGenerationError extends Error {
+    readonly runId: string;
+    readonly expectedGeneration: number;
+    readonly currentGeneration: number;
+    readonly status: ServerRunStatus;
+    constructor(runId: string, expectedGeneration: number, currentGeneration: number, status: ServerRunStatus);
+}
+export interface ApiPrincipal {
+    apiKeyId: string;
+    orgId: string;
+    orgSlug: string;
+    orgName: string;
+    userId: string;
+    email: string;
+    role: string;
+    scopes: string[];
+}
+export interface ServerRunRecord {
+    id: string;
+    orgId: string;
+    userId: string;
+    skill: string;
+    requestedSlug: string;
+    status: ServerRunStatus;
+    input: Record<string, unknown>;
+    args: string[];
+    idempotencyKey?: string;
+    correlationId: string;
+    costCents: number;
+    /**
+     * The cancellation fence. Bumped by every claim and by every cancellation; a
+     * worker that transitions a run while carrying an older generation is writing
+     * against a run it no longer owns and is rejected (see transitionRun).
+     */
+    leaseGeneration: number;
+    outputType?: string;
+    outputPreview?: string;
+    errorCode?: string;
+    errorMessage?: string;
+    createdAt: string;
+    startedAt?: string;
+    completedAt?: string;
+}
+export interface ServerRunLog {
+    runId: string;
+    sequence: number;
+    level: "debug" | "info" | "warn" | "error";
+    message: string;
+    createdAt: string;
+}
+export interface ServerArtifact {
+    id: string;
+    runId: string;
+    orgId: string;
+    fileName: string;
+    relativePath: string;
+    contentType: string;
+    byteSize: number;
+    sha256: string;
+    storageKind: "db" | "s3";
+    storageKey?: string;
+    bodyText?: string;
+    /**
+     * Output visibility. Runs' outputs are PRIVATE by default: the value is set at
+     * write time from the governance default and persisted, never inferred at read
+     * time. "public" is the explicit opt-in for artifacts the tenant intends to
+     * share; it is not a default on any path.
+     */
+    visibility: "private" | "public";
+    /**
+     * Finite retention, set at write time as createdAt + configured TTL. Absent
+     * only when the writing path opted out explicitly; the expiry sweep deletes
+     * artifacts whose expiresAt is in the past and records a deletion receipt.
+     */
+    expiresAt?: string;
+    createdAt: string;
+}
+/** Where bytes actually live. Same vocabulary as ServerArtifact, same meaning. */
+export type BlobStorageKind = "db" | "s3";
+/**
+ * A skill published to this instance by one organization.
+ *
+ * Distinct from `SkillMeta` (src/lib/registry-types.ts), which describes a skill the CLI
+ * knows about from any source. This is the row: it always belongs to an org, and it
+ * always carries the provenance of who put it there.
+ */
+export interface ServerSkillRecord {
+    orgId: string;
+    slug: string;
+    displayName: string;
+    description: string;
+    category: string;
+    tags: string[];
+    source: string;
+    kind: "executable" | "instruction";
+    version?: string;
+    /** The agent-facing document, served verbatim by GET /skills/:slug/skill.md. */
+    skillMd?: string;
+    /** Digest of the stored bundle. Absent for a metadata-only publish. */
+    bundleSha256?: string;
+    bundleByteSize?: number;
+    publishedByUserId?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Bundle bytes, addressed by their own digest.
+ *
+ * `bytes` is present only when the bundle is stored in the database (`storageKind: "db"`).
+ * For S3 the row is a pointer and SkillBundleStorage.read() fetches the object - the same
+ * split ServerArtifact makes between `bodyText` and `storageKey`, except that a bundle is
+ * a gzipped tar and so cannot be a string at any layer.
+ */
+export interface ServerSkillBundle {
+    orgId: string;
+    sha256: string;
+    byteSize: number;
+    contentType: string;
+    storageKind: BlobStorageKind;
+    storageKey?: string;
+    bytes?: OwnedBytes;
+    createdAt: string;
+}
+export interface PublishSkillInput {
+    principal: ApiPrincipal;
+    slug: string;
+    displayName: string;
+    description: string;
+    category: string;
+    tags: string[];
+    source: string;
+    kind: ServerSkillRecord["kind"];
+    version?: string;
+    skillMd?: string;
+    /** Omitted for a metadata-only publish or update. */
+    bundle?: Omit<ServerSkillBundle, "orgId" | "createdAt">;
+}
+/** Metadata-only patch. Never touches the bundle; republish to change bytes. */
+export type UpdateSkillPatch = Partial<Pick<ServerSkillRecord, "displayName" | "description" | "category" | "tags" | "version" | "kind" | "skillMd">>;
+export interface CreateRunInput {
+    principal: ApiPrincipal;
+    slug: string;
+    input: Record<string, unknown>;
+    args: string[];
+    idempotencyKey?: string;
+}
+export interface ClaimRunInput {
+    workerId: string;
+}
+/**
+ * Fields a fenced transition may write, plus the lease_generation the fence
+ * itself bumps on cancellation. Everything updateRun can write plus the
+ * generation counter; the worker never patches the generation, the cancel
+ * service does.
+ */
+export type RunTransitionPatch = Partial<Pick<ServerRunRecord, "status" | "outputType" | "outputPreview" | "errorCode" | "errorMessage" | "startedAt" | "completedAt" | "leaseGeneration">>;
+/**
+ * What a store is, in the only two dimensions the server needs at boot: which backend
+ * it is (for logs and diagnostics) and whether it survives a restart.
+ *
+ * `durable` exists because the server used to boot onto an in-process Map, report
+ * `ok: true` at /health, and lose every run on restart with no warning at any point. A
+ * store that knows it is non-durable can now say so, and startSkillsServer() refuses it
+ * unless the operator explicitly opted in.
+ */
+export interface StoreBackendInfo {
+    /**
+     * The three bundled backends are named for autocomplete; the open `string` arm is
+     * deliberate. This interface is a published seam, and a third-party store must be able
+     * to declare what it is - "mysql", "dynamodb" - without either a type error or having
+     * to misreport itself as one of ours. A closed union would make the seam implementable
+     * only by us, which is the test R3 sets for it.
+     */
+    kind: "postgres" | "sqlite" | "memory" | (string & {});
+    /** False when the data does not survive process exit. */
+    durable: boolean;
+    /** Credential-free description, safe to put in logs and error messages. */
+    label: string;
+}
+export interface SkillsProductStore {
+    /**
+     * Optional so a third-party store implementing this seam keeps compiling. An
+     * undeclared backend is treated as durable: we can refuse what a store tells us is
+     * ephemeral, and cannot infer it about somebody else's implementation. The hazard
+     * actually being closed is our own default, which is now SQLite on disk.
+     */
+    readonly backend?: StoreBackendInfo;
+    /** Release connections and file handles. Optional; not every backend holds any. */
+    close?(): Promise<void>;
+    /**
+     * Prove the backend is actually reachable, throwing if it is not.
+     *
+     * Called once at startup. Bun's SQL client connects lazily, so without this a
+     * Postgres URL pointing at a dead host produced a server that started happily and
+     * then 500ed on the first request.
+     */
+    verifyConnectivity?(): Promise<void>;
+    authenticateApiKeyHash(hash: string): Promise<ApiPrincipal | null>;
+    ensureBootstrapApiKey?(token: string, principal?: Partial<ApiPrincipal>): Promise<void>;
+    createRun(input: CreateRunInput): Promise<ServerRunRecord>;
+    listRuns(principal: ApiPrincipal, limit: number): Promise<ServerRunRecord[]>;
+    getRun(principal: ApiPrincipal, runId: string): Promise<ServerRunRecord | null>;
+    claimNextRun(input: ClaimRunInput): Promise<ServerRunRecord | null>;
+    updateRun(runId: string, patch: Partial<Pick<ServerRunRecord, "status" | "outputType" | "outputPreview" | "errorCode" | "errorMessage" | "startedAt" | "completedAt">>): Promise<ServerRunRecord | null>;
+    /**
+     * Generation-fenced transition, the cancellation gate.
+     *
+     * Optional so a third-party store implementing this seam keeps compiling; the
+     * cancel service requires it and refuses to run without it (FENCING_UNSUPPORTED)
+     * rather than cancelling unfenced. When present it is the ONLY transition the
+     * worker paths use: the UPDATE re-asserts `lease_generation = <expected>` and
+     * reports zero rows when the generation moved on (a newer claim, or a
+     * cancellation), so a late write from a stale worker never lands.
+     *
+     * Returns null when the run does not exist; throws StaleLeaseGenerationError
+     * when the generation no longer matches. The distinction matters: "nothing
+     * there" and "you lost the fence" are different facts.
+     */
+    transitionRun?(runId: string, patch: RunTransitionPatch, expectedGeneration: number): Promise<ServerRunRecord | null>;
+    appendLog(runId: string, orgId: string, level: ServerRunLog["level"], message: string): Promise<ServerRunLog>;
+    listLogs(principal: ApiPrincipal, runId: string): Promise<ServerRunLog[]>;
+    addArtifact(artifact: Omit<ServerArtifact, "createdAt">): Promise<ServerArtifact>;
+    listArtifacts(principal: ApiPrincipal, runId: string): Promise<ServerArtifact[]>;
+    getArtifact(principal: ApiPrincipal, runId: string, artifactId: string): Promise<ServerArtifact | null>;
+    publishSkill(input: PublishSkillInput): Promise<ServerSkillRecord>;
+    listSkills(principal: ApiPrincipal): Promise<ServerSkillRecord[]>;
+    getSkill(principal: ApiPrincipal, slug: string): Promise<ServerSkillRecord | null>;
+    updateSkill(principal: ApiPrincipal, slug: string, patch: UpdateSkillPatch): Promise<ServerSkillRecord | null>;
+    /** False when the org has no skill by that slug. Also drops a bundle nothing else references. */
+    deleteSkill(principal: ApiPrincipal, slug: string): Promise<boolean>;
+    getSkillBundle(principal: ApiPrincipal, sha256: string): Promise<ServerSkillBundle | null>;
+}

package/dist/server/worker.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { ArtifactStorage } from "../sdk/storage.js";
+import type { SkillsProductStore } from "../sdk/storage.js";
+export declare function runWorkerOnce(store: SkillsProductStore, workerId?: string, storage?: ArtifactStorage): Promise<boolean>;

package/dist/storage.js

@@ -1,5 +1,35 @@
 // @bun
+var __create = Object.create;
+var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toESMCache_node;
+var __toESMCache_esm;
+var __toESM = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
+    var cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
+  target = mod != null ? __create(__getProtoOf(mod)) : {};
+  const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
+  for (let key of __getOwnPropNames(mod))
+    if (!__hasOwnProp.call(to, key))
+      __defProp(to, key, {
+        get: __accessProp.bind(mod, key),
+        enumerable: true
+      });
+  if (canCache)
+    cache.set(mod, to);
+  return to;
+};
+var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
 var __returnValue = (v) => v;
 function __exportSetter(name, newValue) {
   this[name] = __returnValue.bind(null, newValue);
@@ -13,6 +43,8 @@ var __export = (target, all) => {
       set: __exportSetter.bind(all, name)
     });
 };
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
+var __require = import.meta.require;
 
 // src/lib/native-storage.ts
 import { createHash, createHmac } from "crypto";

package/docs/skill-standard.md

@@ -17,9 +17,34 @@ Portable skills live in one folder each:
 `skills port <path>` and `skills add <path>` copy an existing skill folder into
 this layout and add missing standard files.
 
+## The manifest split
+
+Two metadata surfaces exist, with one rule: **portable metadata lives in
+`skill.json`; consumer frontmatter stays minimal.**
+
+- `skill.json` is the machine-readable manifest and the **source of truth**
+  for everything the fleet needs to know about a skill: identity, version,
+  runtime contract, provenance. It is the `hasna.skill.v1` contract defined
+  in `schemas/skill.schema.json` (published at
+  `https://hasna.dev/schemas/skill.v1.json`).
+- `SKILL.md` is the agent-facing document. Its frontmatter carries only
+  `name` and `description` (plus `user_invocable: true` where a Claude
+  consumer renderer needs it). Everything else — `kind`, `version`,
+  `source`, `category`, `tags`, `displayName` — lives in `skill.json`.
+  See `docs/authoring-rule-amendment.md` for the proposed fleet rule text.
+
+```yaml
+---
+name: my-skill
+description: What this skill does and when to use it.
+---
+```
+
 ## Skill Kinds
 
-A skill declares its artifact class with the `kind` frontmatter field:
+A skill declares its artifact class with the `kind` field in `skill.json`
+(`kind` may also appear in `SKILL.md` frontmatter for compatibility with
+existing Codewith conventions):
 
 - `kind: executable` (default when omitted) — a runnable skill folder with
   `package.json`, a non-empty `bin`, and `src/index.ts`. `skills run` executes it.
@@ -33,45 +58,65 @@ A skill declares its artifact class with the `kind` frontmatter field:
 Missing `kind` defaults to `executable` so the bundled corpus is unaffected.
 Migrated operational (prose) skills should set `kind: instruction` explicitly.
 
-Minimum `SKILL.md` frontmatter for an instruction skill:
-
-```yaml
----
-name: project
-description: Open or resume an existing Hasna repo project using the projects CLI.
-kind: instruction
-version: 0.1.0
-source: private
----
-```
-
 ## Naming
 
 Skill names are lowercase slugs: letters, numbers, dots, underscores, and
 hyphens. The folder name, `SKILL.md` frontmatter `name`, `skill.json` `name`,
-and `package.json` `name` should match.
-
-## Manifest
-
-Every portable skill needs a manifest. `skill.json` is the machine-readable
-manifest. `SKILL.md` frontmatter stays compatible with existing Codewith
-`SKILL.md` conventions and can be used by agents for skill discovery.
-
-Minimum `SKILL.md` frontmatter:
-
-```yaml
----
-name: my-skill
-description: What this skill does and when to use it.
-version: 0.1.0
-source: custom
-category: Development Tools
-tags:
-  - custom
----
-```
-
-Minimum `skill.json`:
+and `package.json` `name` must match.
+
+## The `hasna.skill.v1` manifest
+
+Every portable skill needs a `skill.json` manifest conforming to
+`hasna.skill.v1` (schema: `schemas/skill.schema.json`). The templates always
+emit a complete valid manifest; `skills validate` rejects one that is
+incomplete, invalid, or whose `content_hash` does not match the bundle.
+
+### Required fields
+
+| field | type | meaning |
+|---|---|---|
+| `standard` | string | `"hasna.skill.v1"` |
+| `name` | string | Lowercase slug; matches the folder name |
+| `description` | string | What this skill does and when to use it |
+| `version` | string | Semver (e.g. `0.1.0`). Any content change requires a version bump |
+| `runtime` | object | The runtime contract below |
+| `provenance` | object | Source and integrity fields; `content_hash` is required |
+
+### Optional fields (legacy-compatible)
+
+| field | type | meaning |
+|---|---|---|
+| `$schema` | string | `https://hasna.dev/schemas/skill.v1.json` |
+| `displayName` | string | Human-facing name |
+| `category` | string | Marketplace / registry category |
+| `tags` | string[] | Searchable tags |
+| `kind` | `"executable" \| "instruction"` | Artifact class |
+| `inputs` | object[] | Declared inputs (`name`, `type`, optional `required`, `description`) |
+| `commands` | object[] | Runnable commands (`name`, `entry`/`command`, optional `args`, `description`) |
+
+### The runtime contract
+
+| field | type | default | meaning |
+|---|---|---|---|
+| `runtime` | `"bun" \| "node" \| "python3"` | *(required)* | Execution runtime. `bun` is the Hasna default |
+| `version` | string | — | Optional runtime version constraint (e.g. `"22"`, `">=3.12"`) |
+| `entrypoint` | string | `commands[0].entry` | Relative path to the runnable entrypoint |
+| `timeout` | integer | `900` | Max execution seconds, **capped at 900** |
+| `needs_network` | boolean | `false` | Whether execution requires network egress |
+| `env` | string[] | `[]` | **Secret REFERENCE names only, never values** — uppercase identifiers such as `OPENAI_API_KEY` |
+| `sandbox` | `"readonly-fs" \| "workspace-write" \| "full"` | `"readonly-fs"` | Filesystem access granted to execution |
+| `system_deps` | string[] | `[]` | Allowlisted system binaries (see schema for the list) |
+| `artifacts` | string[] | `[]` | Glob patterns of artifacts the skill may produce (e.g. `"out/**"`) |
+
+### The provenance fields
+
+| field | type | meaning |
+|---|---|---|
+| `source_commit` | string | Git SHA of the source revision, or `"unknown"` for locally scaffolded skills |
+| `content_hash` | string | **Self-referencing** canonical SHA-256 of the normalized bundle (see below). Required on every manifest |
+| `changelog` | string | Pointer to changelog / release notes (relative path or URL) |
+
+### Example
 
 ```json
 {
@@ -80,6 +125,9 @@ Minimum `skill.json`:
   "name": "my-skill",
   "description": "What this skill does and when to use it.",
   "version": "0.1.0",
+  "displayName": "My Skill",
+  "category": "Development Tools",
+  "tags": ["custom"],
   "inputs": [
     {
       "name": "args",
@@ -95,13 +143,61 @@ Minimum `skill.json`:
       "description": "Run my-skill.",
       "args": ["...args"]
     }
-  ]
+  ],
+  "runtime": {
+    "runtime": "bun",
+    "entrypoint": "src/index.ts",
+    "timeout": 900,
+    "needs_network": false,
+    "env": [],
+    "sandbox": "readonly-fs",
+    "system_deps": [],
+    "artifacts": []
+  },
+  "provenance": {
+    "source_commit": "unknown",
+    "content_hash": "<64 lowercase hex chars>",
+    "changelog": "CHANGELOG.md"
+  }
 }
 ```
 
 If `skill.json` is absent, the CLI can infer a portable manifest from
 `SKILL.md` frontmatter plus `package.json` `bin`, but scaffolded and ported
-skills should keep `skill.json` checked in.
+skills always keep a complete `skill.json` checked in. A manifest present
+without a valid `content_hash` is rejected by `skills validate`.
+
+## Canonical content hashing
+
+`content_hash` is a **self-referencing** SHA-256 over the normalized skill
+bundle:
+
+1. **Coverage** — every file at the skill root (`SKILL.md`, `skill.json`,
+   `AGENTS.md`, `package.json`, `tsconfig.json`) plus every file under
+   `src/`, `scripts/`, `assets/`, and `references/`, recursively.
+2. **Exclusions** — `node_modules`, `.git`, `dist`, `build`, `.turbo`,
+   dot-entries, and symlinks never enter the hash.
+3. **Normalization** — line endings are normalized to LF; for `skill.json`
+   the manifest is **blank-canonicalized**: parsed, its own `content_hash`
+   field (top-level or under `provenance`) removed, and re-serialized with
+   sorted keys. Key order, CRLF, and the hash's own presence therefore never
+   change the digest.
+4. **Determinism** — files are hashed in sorted relative-path order (posix
+   separators), each entry length-prefixed, so the digest is identical on
+   every platform for the same logical content.
+5. **Verification** — `skills validate` recomputes the hash and rejects any
+   manifest whose declared `content_hash` does not match, with the computed
+   value in the error message.
+
+### Versioning rule
+
+**A content change requires a version bump; the same version with different
+content is rejected.** Enforcement is structural: any content change alters
+the canonical bundle, so the declared `content_hash` no longer matches and
+`skills validate` fails (`contract.content_hash_mismatch`). Re-hashing
+without a version bump is still a rejection signal for the registry/server
+later, which pins by version + hash — same semver + different hash is
+unpublishable.
 
 ## Agent Handoff
 
@@ -136,6 +232,11 @@ Validation checks:
 
 - folder and name safety;
 - `SKILL.md` frontmatter compatibility (including a valid `kind`);
+- the `hasna.skill.v1` contract: `standard`, `name`, `description`, `version`
+  (semver), the runtime contract (runtime, timeout cap, sandbox, env reference
+  names, system-deps allowlist), and provenance;
+- the canonical `content_hash`: present, well-formed, and matching the bundle
+  (`contract.content_hash_mismatch` on drift);
 - `skill.json` standard, version, inputs, and commands (relaxed for
   `kind: instruction`, which needs neither `commands`, `inputs`, nor `AGENTS.md`);
 - `AGENTS.md` presence (executable skills only);
@@ -143,6 +244,8 @@ Validation checks:
   optional for `kind: instruction`);
 - no reserved files such as `.env` or symlinks.
 
+An invalid manifest exits non-zero with the exact field errors.
+
 ## Porting Existing Skills
 
 ```bash
@@ -153,4 +256,73 @@ skills add ./old-skill --name new-name
 Porting copies the folder into `~/.hasna/skills/<name>/`, skips generated and
 dependency directories such as `node_modules`, `dist`, and `.git`, then adds or
 normalizes `skill.json`, `AGENTS.md`, `package.json`, `tsconfig.json`, and an
-entrypoint when they are missing.
+entrypoint when they are missing. Missing contract fields (runtime defaults,
+provenance) are filled and the `content_hash` is recomputed over the ported
+bundle; unknown keys in an existing `skill.json` are preserved.
+
+## Machine Layout
+
+The skills app folder (`~/.hasna/skills/`, relocatable with
+`$HASNA_SKILLS_DIR`) hosts the owner layout:
+
+```text
+~/.hasna/skills/
+├── skills/     canonical corpus cache — the sync source
+├── logs/       run/sync logs (created lazily)
+├── outputs/    run outputs (created lazily)
+├── custom/     experiments, retained as-is
+├── config.json
+└── skills.db
+```
+
+`skills/` replaces the older `installed/` corpus home, and legacy flat skill
+dirs that predate `installed/` migrate into it. Both moves are opt-in and
+idempotent:
+
+```bash
+skills storage migrate            # installed/ + legacy dirs -> skills/, creates logs/ + outputs/
+skills storage migrate --dry-run  # show what would move, write nothing
+```
+
+Migration refuses to run against a non-empty `skills/` that carries no
+migration record (`skills/.layout-migration.json`), and never touches
+`custom/`. After a successful migration `skills sync` reads the corpus from
+the new cache automatically.
+
+### Unmarked-home adoption
+
+Agent homes are full of skill directories the CLI never wrote (the ad-hoc
+sed/scp/rsync era). Those carry no `.hasna-skills.json` marker and sync leaves
+them alone by design. Adoption is the migration mode for that population:
+
+```bash
+skills sync --adopt             # dry-run: hash unmarked home skills vs the corpus
+skills sync --adopt --apply     # write markers for exact matches; ledger the rest
+```
+
+Each unmarked home skill's `SKILL.md` is hashed (line endings normalized,
+`user_invocable` stripped) and compared against the canonical corpus cache:
+
+- exact match -> a marker is written and the dir is adopted;
+- content differs -> recorded in `~/.hasna/skills/conflicts.json` (home, skill,
+  hash, canonical hash, mtime) and skipped — an unmarked dir is never
+  overwritten;
+- no canonical entry -> reported as unknown and skipped.
+
+Every written marker is listed in a rollback record under
+`~/.hasna/skills/rollback/`. Nothing is ever deleted by adoption.
+
+### Home drift census
+
+```bash
+skills sync --check             # exits non-zero while drift exists
+```
+
+Compares each existing agent home against the canonical corpus and lists
+`missing-from-home`, `stray-in-home` (marked dir, no canonical entry), and
+`diverged` (marked dir whose hash differs). Unmarked dirs are adoption
+candidates, not drift. `skills diff <name>` and `skills outdated` use the same
+home-vs-canonical comparison; the pinned-skill version comparison remains as a
+subset. `skills sync --prune [--apply]` removes only marked-and-stray dirs,
+recording each removal in the rollback store before it happens.
+

package/migrations/postgres/0003_run_outputs_governance.sql

@@ -0,0 +1,83 @@
+-- Run outputs governance: privacy, retention, cancellation fencing, spend.
+--
+-- Postgres dialect of 0003_run_outputs_governance. Read the SQLite file for why
+-- the migration is additive; the rationale is not repeated here, only the
+-- dialect differences are:
+--   * timestamptz -> text holding a UTC ISO-8601 instant (expires_at, reconciled_at).
+--   * text JSON   -> jsonb (metadata_json).
+--
+-- SQLite has no row-level security; tenant isolation there rests on the
+-- org-scoped predicates in the store and the service-layer negative tests. This
+-- dialect additionally arms PostgreSQL RLS on the two tenant tables, so a
+-- statement that never set the tenant context sees zero rows (fail closed):
+--
+--   CREATE POLICY ... USING (
+--     org_id = current_setting('app.skills_org_id', true)
+--     OR current_setting('app.skills_claim_context', true) = 'worker'
+--   )
+--
+-- The first clause is the principal path: the store runs every tenant-facing
+-- read under SET LOCAL app.skills_org_id = <org>, and an unset setting matches
+-- nothing. The second clause is the worker path, stated as the deliberate
+-- exception it is: skills-worker claims and finalises runs for every org on the
+-- instance (claimNextRun is not org-scoped by design), so it writes under an
+-- explicit claim context rather than a tenant context. Both clauses must be
+-- present for the shipped server to work at all, and neither weakens the tenant
+-- fence: a caller with no context and no claim role reads no tenant rows.
+
+ALTER TABLE skills_runs ADD COLUMN lease_generation integer NOT NULL DEFAULT 0;
+
+ALTER TABLE skills_artifacts ADD COLUMN visibility text NOT NULL DEFAULT 'private';
+ALTER TABLE skills_artifacts ADD COLUMN expires_at timestamptz;
+
+CREATE TABLE IF NOT EXISTS skills_lifecycle_receipts (
+  id text PRIMARY KEY,
+  kind text NOT NULL,
+  org_id text NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+  run_id text NOT NULL REFERENCES skills_runs(id) ON DELETE CASCADE,
+  artifact_id text,
+  requested_by text NOT NULL,
+  metadata_json jsonb NOT NULL DEFAULT '{}'::jsonb,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  CHECK (kind IN ('delete','quarantine','cancel'))
+);
+
+CREATE INDEX IF NOT EXISTS skills_lifecycle_receipts_org_run_idx
+  ON skills_lifecycle_receipts (org_id, run_id);
+
+CREATE TABLE IF NOT EXISTS skills_credit_reservations (
+  id text PRIMARY KEY,
+  org_id text NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+  run_id text NOT NULL REFERENCES skills_runs(id) ON DELETE CASCADE,
+  estimated_cents integer NOT NULL,
+  actual_cents integer,
+  status text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  reconciled_at timestamptz,
+  CHECK (status IN ('reserved','charged','released'))
+);
+
+CREATE INDEX IF NOT EXISTS skills_credit_reservations_org_run_idx
+  ON skills_credit_reservations (org_id, run_id);
+
+ALTER TABLE skills_runs ENABLE ROW LEVEL SECURITY;
+ALTER TABLE skills_artifacts ENABLE ROW LEVEL SECURITY;
+
+-- FORCE closes the owner exemption: Postgres exempts a table's owner from RLS,
+-- and this instance runs migrations and the server as one role, so without
+-- FORCE the fence would not bind the app path. With FORCE the store's
+-- tenant/worker contexts apply to that role like any other.
+ALTER TABLE skills_runs FORCE ROW LEVEL SECURITY;
+ALTER TABLE skills_artifacts FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY skills_runs_tenant_isolation ON skills_runs
+  USING (
+    org_id = current_setting('app.skills_org_id', true)
+    OR current_setting('app.skills_claim_context', true) = 'worker'
+  );
+
+CREATE POLICY skills_artifacts_tenant_isolation ON skills_artifacts
+  USING (
+    org_id = current_setting('app.skills_org_id', true)
+    OR current_setting('app.skills_claim_context', true) = 'worker'
+  );