harnery 0.29.0 → 0.31.0

package/dist/core/artifacts/index.js

@@ -0,0 +1,421 @@
+/**
+ * Repository-local working artifacts.
+ *
+ * Artifacts are file trees that should survive an agent session but should not
+ * become project records: screenshots, exports, audit dumps, rollback inputs,
+ * and similar material. Each direct child of `.harnery/artifacts/` is one
+ * managed unit with a small manifest. Cleanup fails closed: only a valid,
+ * expired, inactive, untracked managed unit is deletable.
+ */
+import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { artifactDefaultRetentionDays } from "../config.js";
+export const ARTIFACTS_DIR = join(".harnery", "artifacts");
+export const ARTIFACT_MANIFEST = ".harnery-artifact.json";
+export const ARTIFACT_SCHEMA_VERSION = 1;
+export function artifactsRoot(repoRoot) {
+    return join(resolve(repoRoot), ARTIFACTS_DIR);
+}
+/** Public config-aware default for embedding hosts that create artifact units. */
+export function configuredArtifactRetentionDays(repoRoot) {
+    return artifactDefaultRetentionDays(repoRoot);
+}
+export function createArtifact(repoRoot, input) {
+    const now = input.now ?? new Date();
+    assertValidDate(now, "now");
+    const slug = normalizeSlug(input.slug);
+    if (!slug)
+        throw new Error("slug must contain at least one ASCII letter or digit");
+    const purpose = input.purpose.trim();
+    if (!purpose)
+        throw new Error("purpose must not be empty");
+    const retentionDays = positiveDays(input.retentionDays);
+    const artifactId = input.id ?? randomUUID();
+    if (!isSafeId(artifactId)) {
+        throw new Error("artifact id must use ASCII letters, digits, hyphens, or underscores");
+    }
+    const root = artifactsRoot(repoRoot);
+    mkdirSync(root, { recursive: true });
+    const date = now.toISOString().slice(0, 10);
+    const path = join(root, `${date}_${slug}_${artifactId.slice(0, 8)}`);
+    mkdirSync(path);
+    const manifest = {
+        schema_version: ARTIFACT_SCHEMA_VERSION,
+        artifact_id: artifactId,
+        slug,
+        purpose,
+        created_at: now.toISOString(),
+        created_by: input.actor,
+        retention: {
+            expires_at: addDays(now, retentionDays).toISOString(),
+        },
+    };
+    atomicWriteManifest(path, manifest);
+    return { path, manifest };
+}
+export function inventoryArtifacts(repoRoot, opts = {}) {
+    const root = artifactsRoot(repoRoot);
+    if (!existsSync(root))
+        return [];
+    const now = opts.now ?? new Date();
+    assertValidDate(now, "now");
+    const freshnessSeconds = opts.freshnessSeconds ?? 600;
+    const rows = [];
+    let names;
+    try {
+        names = readdirSync(root).sort();
+    }
+    catch (error) {
+        return [
+            rowFor(root, basename(root), repoRoot, "unknown", errorMessage("cannot read artifact root", error)),
+        ];
+    }
+    for (const name of names) {
+        rows.push(classifyArtifactPath(repoRoot, join(root, name), now, freshnessSeconds));
+    }
+    return rows;
+}
+export function showArtifact(repoRoot, ref, opts = {}) {
+    const path = resolveArtifactRef(repoRoot, ref);
+    const entry = classifyArtifactPath(repoRoot, path, opts.now ?? new Date(), opts.freshnessSeconds ?? 600);
+    const parsed = readManifest(path);
+    if (!parsed.ok)
+        throw new Error(parsed.reason);
+    return { entry, manifest: parsed.manifest };
+}
+export function renewArtifact(repoRoot, ref, days, reason, input = {}) {
+    const now = input.now ?? new Date();
+    assertValidDate(now, "now");
+    const retentionDays = positiveDays(days);
+    const why = reason.trim();
+    if (!why)
+        throw new Error("renewal reason must not be empty");
+    const path = resolveArtifactRef(repoRoot, ref);
+    const parsed = readManifest(path);
+    if (!parsed.ok)
+        throw new Error(parsed.reason);
+    const manifest = {
+        ...parsed.manifest,
+        retention: {
+            expires_at: addDays(now, retentionDays).toISOString(),
+            renewed_at: now.toISOString(),
+            reason: why,
+        },
+    };
+    atomicWriteManifest(path, manifest);
+    return manifest;
+}
+export function releaseArtifact(repoRoot, ref, input = {}) {
+    const now = input.now ?? new Date();
+    assertValidDate(now, "now");
+    const path = resolveArtifactRef(repoRoot, ref);
+    const parsed = readManifest(path);
+    if (!parsed.ok)
+        throw new Error(parsed.reason);
+    const manifest = {
+        ...parsed.manifest,
+        released_at: now.toISOString(),
+        released_by: input.actor,
+    };
+    atomicWriteManifest(path, manifest);
+    return manifest;
+}
+export function cleanArtifacts(repoRoot, opts = {}) {
+    const now = opts.now ?? new Date();
+    const freshnessSeconds = opts.freshnessSeconds ?? 600;
+    const rows = inventoryArtifacts(repoRoot, { now, freshnessSeconds });
+    if (!opts.yes)
+        return rows;
+    return rows.map((entry) => {
+        if (entry.classification !== "managed-expired")
+            return entry;
+        // Reclassify immediately before removal. A renewal, release-state change,
+        // heartbeat, symlink swap, or tracked file added since inventory must win.
+        const current = classifyArtifactPath(repoRoot, entry.path, now, freshnessSeconds);
+        if (current.classification !== "managed-expired")
+            return current;
+        try {
+            const top = lstatSync(current.path);
+            if (!top.isDirectory() || top.isSymbolicLink()) {
+                return {
+                    ...current,
+                    classification: "unknown",
+                    reason: "entry changed before deletion",
+                    action: "keep",
+                };
+            }
+            rmSync(current.path, { recursive: true, force: false });
+            return { ...current, action: "deleted" };
+        }
+        catch (error) {
+            return {
+                ...current,
+                classification: "unknown",
+                reason: errorMessage("entry changed or could not be deleted", error),
+                action: "keep",
+            };
+        }
+    });
+}
+export function resolveArtifactRef(repoRoot, ref) {
+    const root = artifactsRoot(repoRoot);
+    const candidate = isAbsolute(ref) ? resolve(ref) : resolve(root, ref);
+    if (candidate === root || !candidate.startsWith(`${root}${sep}`) || dirname(candidate) !== root) {
+        // A bare artifact id is the only non-path lookup. It must match exactly,
+        // never by prefix, so two UUIDs cannot make a command ambiguous.
+        const matches = inventoryArtifacts(repoRoot)
+            .filter((entry) => entry.artifact_id === ref)
+            .map((entry) => entry.path);
+        if (matches.length === 1)
+            return matches[0];
+        throw new Error(`artifact "${ref}" was not found`);
+    }
+    if (!existsSync(candidate)) {
+        const matches = inventoryArtifacts(repoRoot)
+            .filter((entry) => entry.artifact_id === ref)
+            .map((entry) => entry.path);
+        if (matches.length === 1)
+            return matches[0];
+        throw new Error(`artifact "${ref}" was not found`);
+    }
+    return candidate;
+}
+function classifyArtifactPath(repoRoot, path, now, freshnessSeconds) {
+    const name = basename(path);
+    let st;
+    try {
+        st = lstatSync(path);
+    }
+    catch (error) {
+        return rowFor(path, name, repoRoot, "unknown", errorMessage("cannot inspect entry", error));
+    }
+    if (st.isSymbolicLink()) {
+        return rowFor(path, name, repoRoot, "symlink", "symlinks are never traversed or deleted");
+    }
+    if (!st.isDirectory()) {
+        return rowFor(path, name, repoRoot, "unmanaged", "workspace entries must be directories");
+    }
+    const parsed = readManifest(path);
+    if (!parsed.ok) {
+        const classification = existsSync(join(path, ARTIFACT_MANIFEST))
+            ? "invalid-manifest"
+            : "unmanaged";
+        return rowFor(path, name, repoRoot, classification, parsed.reason);
+    }
+    const manifest = parsed.manifest;
+    const bytes = safeTreeSize(path);
+    const base = rowFor(path, name, repoRoot, "managed-current", "retention has not expired", bytes);
+    Object.assign(base, {
+        artifact_id: manifest.artifact_id,
+        slug: manifest.slug,
+        created_at: manifest.created_at,
+        expires_at: manifest.retention.expires_at,
+        owner_instance_id: manifest.created_by?.instance_id ?? null,
+    });
+    if (base.bytes === null) {
+        return {
+            ...base,
+            classification: "unknown",
+            reason: "one or more artifact paths are unreadable",
+            action: "keep",
+        };
+    }
+    if (containsTrackedPath(repoRoot, path)) {
+        return {
+            ...base,
+            classification: "managed-tracked",
+            reason: "Git tracks one or more paths inside this artifact",
+            action: "keep",
+        };
+    }
+    if (!manifest.released_at && manifest.created_by?.instance_id) {
+        const live = ownerLiveness(repoRoot, manifest.created_by.instance_id, now, freshnessSeconds);
+        if (live === "live") {
+            return {
+                ...base,
+                classification: "managed-active",
+                reason: `owner ${manifest.created_by.instance_id} has a fresh heartbeat`,
+                action: "keep",
+            };
+        }
+        if (live === "unknown") {
+            return {
+                ...base,
+                classification: "unknown",
+                reason: `owner ${manifest.created_by.instance_id} heartbeat is unreadable`,
+                action: "keep",
+            };
+        }
+    }
+    if (Date.parse(manifest.retention.expires_at) > now.getTime())
+        return base;
+    return {
+        ...base,
+        classification: "managed-expired",
+        reason: `retention expired at ${manifest.retention.expires_at}`,
+        action: "would-delete",
+    };
+}
+function readManifest(path) {
+    const manifestPath = join(path, ARTIFACT_MANIFEST);
+    if (!existsSync(manifestPath)) {
+        return { ok: false, reason: `missing ${ARTIFACT_MANIFEST}` };
+    }
+    let value;
+    try {
+        value = JSON.parse(readFileSync(manifestPath, "utf8"));
+    }
+    catch (error) {
+        return { ok: false, reason: errorMessage("manifest is unreadable", error) };
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return { ok: false, reason: "manifest must be a JSON object" };
+    }
+    const m = value;
+    if (m.schema_version !== ARTIFACT_SCHEMA_VERSION) {
+        return { ok: false, reason: `unsupported schema_version ${String(m.schema_version)}` };
+    }
+    if (!isSafeId(m.artifact_id))
+        return { ok: false, reason: "invalid artifact_id" };
+    if (typeof m.slug !== "string" || !m.slug || normalizeSlug(m.slug) !== m.slug) {
+        return { ok: false, reason: "invalid slug" };
+    }
+    if (typeof m.purpose !== "string" || !m.purpose.trim()) {
+        return { ok: false, reason: "invalid purpose" };
+    }
+    if (!validIso(m.created_at))
+        return { ok: false, reason: "invalid created_at" };
+    if (!m.retention || typeof m.retention !== "object" || !validIso(m.retention.expires_at)) {
+        return { ok: false, reason: "invalid retention.expires_at" };
+    }
+    if (m.released_at !== undefined && !validIso(m.released_at)) {
+        return { ok: false, reason: "invalid released_at" };
+    }
+    if (m.created_by !== undefined && !validActor(m.created_by)) {
+        return { ok: false, reason: "invalid created_by" };
+    }
+    if (m.released_by !== undefined && !validActor(m.released_by)) {
+        return { ok: false, reason: "invalid released_by" };
+    }
+    return { ok: true, manifest: m };
+}
+function atomicWriteManifest(path, manifest) {
+    const target = join(path, ARTIFACT_MANIFEST);
+    const tmp = `${target}.tmp.${process.pid}.${randomUUID().slice(0, 8)}`;
+    writeFileSync(tmp, `${JSON.stringify(manifest, null, 2)}\n`, {
+        encoding: "utf8",
+        mode: 0o600,
+    });
+    renameSync(tmp, target);
+}
+function ownerLiveness(repoRoot, instanceId, now, freshnessSeconds) {
+    const path = join(repoRoot, ".harnery", "active", `${instanceId}.json`);
+    if (!existsSync(path))
+        return "stale";
+    try {
+        const hb = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof hb.last_heartbeat !== "string")
+            return "unknown";
+        const ts = Date.parse(hb.last_heartbeat);
+        if (!Number.isFinite(ts))
+            return "unknown";
+        return now.getTime() - ts <= freshnessSeconds * 1000 ? "live" : "stale";
+    }
+    catch {
+        return "unknown";
+    }
+}
+function containsTrackedPath(repoRoot, path) {
+    const rel = relative(repoRoot, path);
+    if (rel.startsWith("..") || isAbsolute(rel))
+        return true;
+    const result = spawnSync("git", ["ls-files", "-z", "--", rel], {
+        cwd: repoRoot,
+        encoding: "utf8",
+    });
+    // If Git itself cannot answer, fail closed.
+    return result.status !== 0 || result.stdout.length > 0;
+}
+function safeTreeSize(path) {
+    try {
+        const st = lstatSync(path);
+        if (st.isSymbolicLink())
+            return st.size;
+        if (st.isFile())
+            return st.size;
+        if (!st.isDirectory())
+            return 0;
+        let total = st.size;
+        for (const child of readdirSync(path)) {
+            const size = safeTreeSize(join(path, child));
+            if (size === null)
+                return null;
+            total += size;
+        }
+        return total;
+    }
+    catch {
+        return null;
+    }
+}
+function rowFor(path, name, repoRoot, classification, reason, bytes = safeTreeSize(path)) {
+    return {
+        name,
+        path,
+        relative_path: relative(repoRoot, path),
+        classification,
+        reason,
+        action: classification === "managed-expired" ? "would-delete" : "keep",
+        bytes,
+        artifact_id: null,
+        slug: null,
+        created_at: null,
+        expires_at: null,
+        owner_instance_id: null,
+    };
+}
+function normalizeSlug(value) {
+    // Collapsing every non-alphanumeric run to a single "-" leaves no two
+    // adjacent dashes, so trimming the edges needs fixed-length patterns rather
+    // than "-+", whose backtracking is polynomial on a long run of dashes.
+    const collapsed = value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-");
+    return collapsed.replace(/^-/, "").replace(/-$/, "").slice(0, 64);
+}
+function positiveDays(value) {
+    if (!Number.isInteger(value) || value <= 0 || value > 3650) {
+        throw new Error("retention days must be between 1 and 3650");
+    }
+    return value;
+}
+function addDays(date, days) {
+    return new Date(date.getTime() + days * 24 * 60 * 60 * 1000);
+}
+function isSafeId(value) {
+    return (typeof value === "string" &&
+        value.length >= 8 &&
+        value.length <= 128 &&
+        /^[A-Za-z0-9_-]+$/.test(value));
+}
+function validActor(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const actor = value;
+    return (isSafeId(actor.instance_id) &&
+        (actor.session_id === undefined || isSafeId(actor.session_id)) &&
+        (actor.name === undefined || (typeof actor.name === "string" && actor.name.length <= 128)));
+}
+function validIso(value) {
+    return typeof value === "string" && Number.isFinite(Date.parse(value));
+}
+function assertValidDate(value, label) {
+    if (!Number.isFinite(value.getTime()))
+        throw new Error(`${label} must be a valid date`);
+}
+function errorMessage(prefix, error) {
+    return `${prefix}: ${error instanceof Error ? error.message : String(error)}`;
+}

package/dist/core/config.d.ts

@@ -8,8 +8,9 @@
  *
  * Fields owned here: `binName` (host CLI name for agent-facing strings),
  * `hooksSetupHint`, `tools`, `workflow`, `skills`, `presence`, plus the tunable
- * `coord` (heartbeat freshness), `backup` (restic repo/password/prune policy),
- * and `sync` (rclone remote/prefix) sections. The `files` deny/override section
+ * `coord` (heartbeat freshness), `artifacts` (working-file retention),
+ * `backup` (restic repo/password/prune policy), and `sync` (rclone
+ * remote/prefix) sections. The `files` deny/override section
  * is parsed separately by `web/lib/files.ts`.
  *
  * Env vars and CLI flags override any config value per invocation (each accessor
@@ -91,6 +92,12 @@ export declare function presenceRelayUrl(coordRoot?: string | null): string | nu
  * `coordRoot` is resolved via `findCoordRoot()` when not passed.
  */
 export declare function coordFreshnessSeconds(coordRoot?: string | null): number;
+/**
+ * Default retention for a newly-created working artifact. Precedence:
+ * `HARNERY_ARTIFACT_RETENTION_DAYS` -> project/user config
+ * `artifacts.default_retention_days` -> 3 days.
+ */
+export declare function artifactDefaultRetentionDays(coordRoot?: string | null): number;
 /** Resolved `harn backup` defaults (restic repo/password + prune policy). */
 export interface BackupConfig {
     repo: string;

package/dist/core/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAQH,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,SAAS,CAAC;AAEvC,yFAAyF;AACzF,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAiE1C,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAqCvD;AAwFD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAShE;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGhE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAK9E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAOrE;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAO3E;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAOlE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAWzE;AAQD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CASvE;AAED,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,YAAY,CAmBpE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GACxB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAS3C"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/core/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAQH,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,SAAS,CAAC;AAEvC,yFAAyF;AACzF,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAsE1C,8FAA8F;AAC9F,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAqCvD;AAwFD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAShE;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGhE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAK9E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAOrE;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAO3E;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAOlE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAWzE;AAQD;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CASvE;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAe9E;AAED,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,YAAY,CAmBpE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GACxB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAS3C"}

package/dist/core/config.js

@@ -8,8 +8,9 @@
  *
  * Fields owned here: `binName` (host CLI name for agent-facing strings),
  * `hooksSetupHint`, `tools`, `workflow`, `skills`, `presence`, plus the tunable
- * `coord` (heartbeat freshness), `backup` (restic repo/password/prune policy),
- * and `sync` (rclone remote/prefix) sections. The `files` deny/override section
+ * `coord` (heartbeat freshness), `artifacts` (working-file retention),
+ * `backup` (restic repo/password/prune policy), and `sync` (rclone
+ * remote/prefix) sections. The `files` deny/override section
  * is parsed separately by `web/lib/files.ts`.
  *
  * Env vars and CLI flags override any config value per invocation (each accessor
@@ -294,6 +295,29 @@ export function coordFreshnessSeconds(coordRoot) {
         return posIntOr(readConfig(root).coord?.freshness_seconds, DEFAULT_FRESHNESS_SECS);
     return DEFAULT_FRESHNESS_SECS;
 }
+/**
+ * Default retention for a newly-created working artifact. Precedence:
+ * `HARNERY_ARTIFACT_RETENTION_DAYS` -> project/user config
+ * `artifacts.default_retention_days` -> 3 days.
+ */
+export function artifactDefaultRetentionDays(coordRoot) {
+    const env = coordEnv("ARTIFACT_RETENTION_DAYS");
+    if (env !== undefined) {
+        const n = Number(env);
+        if (Number.isFinite(n) && n > 0 && n <= 3650)
+            return n;
+    }
+    const root = coordRoot ?? findCoordRoot();
+    if (!root)
+        return 3;
+    const configured = readConfig(root).artifacts?.default_retention_days;
+    return typeof configured === "number" &&
+        Number.isFinite(configured) &&
+        configured > 0 &&
+        configured <= 3650
+        ? configured
+        : 3;
+}
 /**
  * `harn backup` (restic) defaults. Per field, precedence is env → config → built-in:
  *   repo:          `HARNERY_RESTIC_REPO` → `backup.repo` → `~/.cache/harnery/restic-repo`

package/dist/core/context/index.d.ts

@@ -1,10 +1,10 @@
 /**
- * Context continuity: durable, structured state around native harness
- * compaction. Harnery does not decide when a harness compacts. It records
- * context telemetry when the harness exposes it, checkpoints external work
+ * Context continuity: durable, structured state around native adapter
+ * compaction. Harnery does not decide when a adapter compacts. It records
+ * context telemetry when the adapter exposes it, checkpoints external work
  * state before compaction, and renders a verified recovery briefing after it.
  */
-import type { Harness } from "../hooks/events/schema.js";
+import type { Adapter } from "../hooks/events/schema.js";
 export declare const CONTEXT_SCHEMA_VERSION: 1;
 export declare const MAX_CAPSULE_BYTES: number;
 export type ContextSampleSource = "hook" | "native_event" | "result" | "transcript" | "estimate";
@@ -13,7 +13,7 @@ export type ContextPhase = "observing" | "checkpointed" | "recovered" | "degrade
 export type CheckpointReason = "manual" | "pressure" | "pre_compact" | "session_end";
 export interface ContextSample {
     session_id: string;
-    harness: Harness;
+    adapter: Adapter;
     model?: string;
     used_tokens?: number;
     window_tokens?: number;
@@ -52,7 +52,7 @@ export interface ContinuityCapsule {
     session: {
         session_id: string;
         instance_id: string;
-        harness: Harness;
+        adapter: Adapter;
         model?: string;
     };
     context?: ContextSample;
@@ -69,7 +69,7 @@ export interface ContinuityCapsule {
 }
 export interface ExtractContextSampleOptions {
     sessionId: string;
-    harness: Harness;
+    adapter: Adapter;
     model?: string;
     source?: ContextSampleSource;
     confidence?: ContextSampleConfidence;
@@ -78,7 +78,7 @@ export interface ExtractContextSampleOptions {
 export interface CheckpointContextInput {
     sessionId: string;
     instanceId: string;
-    harness: Harness;
+    adapter: Adapter;
     cwd: string;
     reason: CheckpointReason;
     model?: string;
@@ -101,7 +101,7 @@ export interface PreparedContextRecovery {
     capsule: ContinuityCapsule;
     briefing: string;
 }
-/** Parse the context-window shapes exposed by current harness hook/status data. */
+/** Parse the context-window shapes exposed by current adapter hook/status data. */
 export declare function extractContextSample(payload: Record<string, unknown>, options: ExtractContextSampleOptions): ContextSample | null;
 /** Persist a latest context sample. Identical measurements are a no-op. */
 export declare function recordContextSample(coordRoot: string, instanceId: string, sample: ContextSample): {
@@ -114,18 +114,18 @@ export declare function recordContextSample(coordRoot: string, instanceId: strin
  * create a new generation.
  */
 export declare function checkpointContext(coordRoot: string, input: CheckpointContextInput): CheckpointContextResult;
-/** Prepare a briefing without claiming that a harness has accepted it yet. */
+/** Prepare a briefing without claiming that a adapter has accepted it yet. */
 export declare function prepareContextRecovery(coordRoot: string, input: {
     sessionId: string;
     instanceId: string;
     cwd: string;
 }): PreparedContextRecovery | null;
-/** Advance continuity only after the harness context channel accepted the briefing. */
+/** Advance continuity only after the adapter context channel accepted the briefing. */
 export declare function completeContextRecovery(coordRoot: string, input: {
     sessionId: string;
     instanceId: string;
 }): ContextContinuityState;
-/** Record that the harness, rather than Harnery, reported compaction complete. */
+/** Record that the adapter, rather than Harnery, reported compaction complete. */
 export declare function markContextCompactionCompleted(coordRoot: string, input: {
     sessionId: string;
     instanceId: string;

package/dist/core/context/index.js

@@ -1,7 +1,7 @@
 /**
- * Context continuity: durable, structured state around native harness
- * compaction. Harnery does not decide when a harness compacts. It records
- * context telemetry when the harness exposes it, checkpoints external work
+ * Context continuity: durable, structured state around native adapter
+ * compaction. Harnery does not decide when a adapter compacts. It records
+ * context telemetry when the adapter exposes it, checkpoints external work
  * state before compaction, and renders a verified recovery briefing after it.
  */
 import { spawnSync } from "node:child_process";
@@ -12,7 +12,7 @@ export const CONTEXT_SCHEMA_VERSION = 1;
 export const MAX_CAPSULE_BYTES = 32 * 1024;
 const MAX_SNAPSHOT_PATHS = 15;
 const MAX_SNAPSHOT_PATH_CHARS = 500;
-/** Parse the context-window shapes exposed by current harness hook/status data. */
+/** Parse the context-window shapes exposed by current adapter hook/status data. */
 export function extractContextSample(payload, options) {
     const contextValue = payload.context_window;
     const context = record(contextValue);
@@ -48,7 +48,7 @@ export function extractContextSample(payload, options) {
         string(record(payload.model)?.display_name);
     return {
         session_id: options.sessionId,
-        harness: options.harness,
+        adapter: options.adapter,
         model,
         used_tokens: usedTokens,
         window_tokens: windowTokens,
@@ -105,7 +105,7 @@ export function checkpointContext(coordRoot, input) {
         session: {
             session_id: input.sessionId,
             instance_id: input.instanceId,
-            harness: input.harness,
+            adapter: input.adapter,
             model: input.model ?? current.latest_context?.model ?? heartbeat?.model,
         },
         context: current.latest_context,
@@ -129,7 +129,7 @@ export function checkpointContext(coordRoot, input) {
     writeState(coordRoot, next);
     return { capsule, path: absolutePath, state: next, reused: false };
 }
-/** Prepare a briefing without claiming that a harness has accepted it yet. */
+/** Prepare a briefing without claiming that a adapter has accepted it yet. */
 export function prepareContextRecovery(coordRoot, input) {
     const now = new Date().toISOString();
     const current = readContextState(coordRoot, input.sessionId) ??
@@ -150,7 +150,7 @@ export function prepareContextRecovery(coordRoot, input) {
     const briefing = renderRecoveryBriefing(capsule, liveRepo);
     return { state: current, capsule, briefing };
 }
-/** Advance continuity only after the harness context channel accepted the briefing. */
+/** Advance continuity only after the adapter context channel accepted the briefing. */
 export function completeContextRecovery(coordRoot, input) {
     const now = new Date().toISOString();
     const current = readContextState(coordRoot, input.sessionId) ??
@@ -166,7 +166,7 @@ export function completeContextRecovery(coordRoot, input) {
     writeState(coordRoot, recovered);
     return recovered;
 }
-/** Record that the harness, rather than Harnery, reported compaction complete. */
+/** Record that the adapter, rather than Harnery, reported compaction complete. */
 export function markContextCompactionCompleted(coordRoot, input) {
     const now = input.observedAt ?? new Date().toISOString();
     const current = readContextState(coordRoot, input.sessionId) ??
@@ -344,7 +344,7 @@ function git(cwd, args) {
 function sameMeasurement(a, b) {
     if (!a)
         return false;
-    return (a.harness === b.harness &&
+    return (a.adapter === b.adapter &&
         a.model === b.model &&
         a.used_tokens === b.used_tokens &&
         a.window_tokens === b.window_tokens &&