@indigoai-us/hq-cli 5.345.154 → 5.345.155

package/dist/commands/library.d.ts

@@ -1,7 +1,8 @@
 import { Command } from "commander";
 import { type CloudPlaceholder } from "@indigoai-us/hq-cloud";
 import { type SearchCollection } from "../lib/search-index/index.js";
-import { type LibraryAddResult } from "./library-add.js";
+import { type CompaniesManifestMap } from "../lib/work-context/repo-remote.js";
+import { type LibraryCompany, type LibraryAddResult } from "./library-add.js";
 /** Mirrors hq-pro's MAX_ASSET_SEARCH_TAGS / tag length bound. */
 export declare const MAX_LIBRARY_SEARCH_TAGS = 20;
 export interface LibrarySearchOptions {
@@ -68,5 +69,29 @@ export declare function searchLocalAssets(query: string, options: LibrarySearchO
 export declare function listLibraryAssets(hqRoot: string, directory: string, tags: readonly string[], env?: Pick<LocalSearchEnv, "readFile" | "listPlaceholders">): LibraryAssetHit[];
 export declare function formatLibraryResult(result: LibrarySearchResult): string;
 export declare function formatLibraryAddResult(result: LibraryAddResult): string;
+/**
+ * The company for a library command run on an HQ_API_KEY, from a slug or a
+ * cmp_ uid. A key cannot read memberships (hq-pro serves no keyed
+ * /membership/me) and is bound to one company, which hq-pro checks on every
+ * keyed presign. So the slug ↔ uid mapping comes from the HQ tree's
+ * companies/manifest.yaml (`<slug>: { cloud_uid }`), as `hq secrets` does,
+ * and a key minted for another company is refused by the server.
+ * `folderSlug` is the companies/<slug>/ of an explicit `--to`.
+ */
+export declare function libraryCompanyForApiKey(manifest: CompaniesManifestMap | null, ref: string, folderSlug?: string): LibraryCompany;
+/**
+ * The company uid for `hq library link` on an HQ_API_KEY. A cmp_ uid passes
+ * through (hq-pro checks it against the key). A slug, from --company or from
+ * the placeholder's folder, maps through companies/manifest.yaml. With
+ * neither --company nor a placeholder, or with HQ_COMPANY_UID set and no
+ * --company, the existing key default applies (`fallback`). An explicit
+ * --company always wins: `--company <slug>` maps through the manifest even
+ * when HQ_COMPANY_UID is set, and the env uid is ignored.
+ */
+export declare function libraryLinkCompanyForApiKey(ref: string | undefined, placeholderSlug: string | undefined, deps: {
+    manifest: () => CompaniesManifestMap | null;
+    envCompanyUid?: string;
+    fallback: () => Promise<string>;
+}): Promise<string>;
 export declare function registerLibraryCommand(program: Command): void;
 //# sourceMappingURL=library.d.ts.map

package/dist/commands/library.js

@@ -1,7 +1,8 @@
 /**
- * `hq library search|add|tag|ls|fetch|describe|link` — the company media library.
+ * `hq library search|add|tag|ls|fetch|describe|link|rm` — the company media library.
  * `add` and `tag` live in ./library-add.ts; AI captions (`add` and `describe`)
- * live in ./library-caption.ts; `link` lives in ./library-link.ts; `fetch`
+ * live in ./library-caption.ts; `link` lives in ./library-link.ts; `rm` lives in
+ * ./library-remove.ts; `fetch`
  * wraps `hq storage fetch`.
  *
  * `hq library search <query> [--tag t] [--json]` — find library assets.
@@ -34,10 +35,12 @@ import { ASSET_COLLECTION_MASK, deriveCollections, runQmd, } from "../lib/search
 import { findHqRoot } from "../utils/manifest.js";
 import { networkTransportErrorCode } from "../utils/network-transport-error.js";
 import { resolveVaultCredentialForCapability } from "../utils/resolve-vault-credential.js";
-import { getCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
+import { getCompanyUid, looksLikeCompanyUid, vaultApiFetch } from "../utils/vault-api.js";
+import { readCompaniesManifestMap } from "../lib/work-context/repo-remote.js";
 import { defaultLibraryIo, resolveLibrarySyncScope, runLibraryAdd, runLibraryTag, } from "./library-add.js";
 import { captionAddedAsset, extractCaptionFrames, runLibraryDescribe, runLocalClaude } from "./library-caption.js";
 import { LIBRARY_LINK_DEFAULT_MINUTES, LIBRARY_LINK_MAX_MINUTES, runLibraryLink } from "./library-link.js";
+import { registerLibraryRemoveCommand } from "./library-remove.js";
 /** Mirrors hq-pro's MAX_ASSET_SEARCH_TAGS / tag length bound. */
 export const MAX_LIBRARY_SEARCH_TAGS = 20;
 const MAX_TAG_LENGTH = 100;
@@ -335,17 +338,92 @@ async function downloadPresigned(url) {
         throw new Error(`Could not download the asset (HTTP ${res.status}).`);
     return Readable.fromWeb(res.body);
 }
-/** The active company membership for `slug`, via /membership/me. */
-async function libraryCompany(token, slug) {
+/** The active company membership for `ref` (slug or cmp_ uid), via /membership/me. */
+async function libraryCompany(token, ref) {
     const { companiesFromMemberships } = await import("./storage.js");
     const res = await vaultApiFetch({ token, path: "/membership/me" });
     if (!res.ok)
         throw new Error(`Could not load your companies (HTTP ${res.status}). Run \`hq login\`.`);
-    const company = companiesFromMemberships(await res.json()).find((c) => c.slug === slug);
+    const company = companiesFromMemberships(await res.json()).find((c) => c.slug === ref || c.uid === ref);
     if (!company)
-        throw new Error(`You are not an active member of '${slug}'.`);
+        throw new Error(`You are not an active member of '${ref}'.`);
     return { uid: company.uid, slug: company.slug };
 }
+/**
+ * The company for a library command run on an HQ_API_KEY, from a slug or a
+ * cmp_ uid. A key cannot read memberships (hq-pro serves no keyed
+ * /membership/me) and is bound to one company, which hq-pro checks on every
+ * keyed presign. So the slug ↔ uid mapping comes from the HQ tree's
+ * companies/manifest.yaml (`<slug>: { cloud_uid }`), as `hq secrets` does,
+ * and a key minted for another company is refused by the server.
+ * `folderSlug` is the companies/<slug>/ of an explicit `--to`.
+ */
+export function libraryCompanyForApiKey(manifest, ref, folderSlug) {
+    const uidFor = (slug) => {
+        const uid = manifest?.[slug]?.cloud_uid;
+        return typeof uid === "string" && looksLikeCompanyUid(uid) ? uid : undefined;
+    };
+    // A missing or unparsable manifest is its own problem: say so rather than
+    // report a missing cloud_uid. A uid with an explicit --to folder needs no
+    // lookup, so it still goes through.
+    if (manifest === null && (!looksLikeCompanyUid(ref) || folderSlug === undefined)) {
+        throw new Error(`HQ_API_KEY is set and companies/manifest.yaml could not be read (missing or not valid YAML), ` +
+            `so '${ref}' cannot be matched to a company. Fix the manifest, or pass --company <cmp_uid> ` +
+            "(for library add, with --to companies/<slug>/<dir>).");
+    }
+    if (!looksLikeCompanyUid(ref)) {
+        const uid = uidFor(ref);
+        if (!uid) {
+            throw new Error(`HQ_API_KEY is set and companies/manifest.yaml has no cloud_uid for '${ref}'. ` +
+                `Pass --company <cmp_uid> (for library add, with --to companies/${ref}/<dir>).`);
+        }
+        return { uid, slug: ref };
+    }
+    if (folderSlug !== undefined) {
+        const known = uidFor(folderSlug);
+        if (known !== undefined && known !== ref) {
+            throw new Error(`--to is inside companies/${folderSlug}/, which is ${known}, but --company is ${ref}.`);
+        }
+        return { uid: ref, slug: folderSlug };
+    }
+    const slugs = Object.keys(manifest ?? {}).filter((slug) => !looksLikeCompanyUid(slug) && uidFor(slug) === ref);
+    if (slugs.length !== 1) {
+        throw new Error(`HQ_API_KEY is set and companies/manifest.yaml ${slugs.length === 0 ? "names no company folder" : `names ${slugs.length} company folders`} for ${ref}. Pass --company <slug> or --to companies/<slug>/<dir>.`);
+    }
+    return { uid: ref, slug: slugs[0] };
+}
+/**
+ * The company uid for `hq library link` on an HQ_API_KEY. A cmp_ uid passes
+ * through (hq-pro checks it against the key). A slug, from --company or from
+ * the placeholder's folder, maps through companies/manifest.yaml. With
+ * neither --company nor a placeholder, or with HQ_COMPANY_UID set and no
+ * --company, the existing key default applies (`fallback`). An explicit
+ * --company always wins: `--company <slug>` maps through the manifest even
+ * when HQ_COMPANY_UID is set, and the env uid is ignored.
+ */
+export async function libraryLinkCompanyForApiKey(ref, placeholderSlug, deps) {
+    if (ref !== undefined && looksLikeCompanyUid(ref))
+        return ref;
+    const slug = ref ?? (deps.envCompanyUid ? undefined : placeholderSlug);
+    if (slug === undefined)
+        return deps.fallback();
+    return libraryCompanyForApiKey(deps.manifest(), slug).uid;
+}
+function manifestOrNull() {
+    try {
+        return readCompaniesManifestMap(findHqRoot());
+    }
+    catch {
+        return null;
+    }
+}
+/** Company resolver for `add` and `describe`: memberships on a session, the manifest on a key. */
+function libraryCompanyResolver(credential, hqRoot) {
+    if (credential.kind === "api-key") {
+        return async (ref, folderSlug) => libraryCompanyForApiKey(readCompaniesManifestMap(hqRoot), ref, folderSlug);
+    }
+    return (ref) => libraryCompany(credential.token, ref);
+}
 export function registerLibraryCommand(program) {
     const library = program
         .command("library")
@@ -392,7 +470,7 @@ export function registerLibraryCommand(program) {
         .option("--tags <tags>", "Tags (comma-separated, repeatable)", collectTag, [])
         .option("--title <title>", "Asset title (default: the file name)")
         .option("--note <text>", "Asset description")
-        .option("--company <slug>", "Company whose vault receives the files")
+        .option("--company <company>", "Company slug or uid (cmp_…) whose vault receives the files")
         .option("--no-caption", "Skip the AI description and suggested tags for images and videos")
         .option("--json", "Print machine-readable JSON")
         .action(async (sources, options) => {
@@ -411,7 +489,7 @@ export function registerLibraryCommand(program) {
             }, {
                 hqRoot,
                 now: () => new Date(),
-                resolveCompany: (slug) => libraryCompany(token, slug),
+                resolveCompany: libraryCompanyResolver(credential, hqRoot),
                 presign: (body) => vaultApiFetch({ token, path: "/v1/files/presign", method: "POST", body }),
                 ...defaultLibraryIo,
                 ...(await librarySyncScopeDeps(credential, hqRoot)),
@@ -482,13 +560,15 @@ export function registerLibraryCommand(program) {
         .option("--json", "Print machine-readable JSON")
         .action(async (target, options) => {
         try {
-            const { token } = await resolveVaultCredentialForCapability("files:read", "library describe", {
+            const credential = await resolveVaultCredentialForCapability("files:read", "library describe", {
                 interactive: true,
             });
+            const { token } = credential;
+            const hqRoot = findHqRoot();
             const result = await runLibraryDescribe(target, {
-                hqRoot: findHqRoot(),
+                hqRoot,
                 now: () => new Date(),
-                resolveCompany: (slug) => libraryCompany(token, slug),
+                resolveCompany: libraryCompanyResolver(credential, hqRoot),
                 presign: (body) => vaultApiFetch({ token, path: "/v1/files/presign", method: "POST", body }),
                 download: downloadPresigned,
                 runLocal: runLocalClaude,
@@ -532,7 +612,7 @@ export function registerLibraryCommand(program) {
         .command("link")
         .description("Mint a short-lived download URL for a library asset (needs files:read)")
         .argument("<target>", "A .hqcloud placeholder, its original path, or a vault key (.hq-offload/…)")
-        .option("--company <company>", "Company uid (cmp_…), or a slug on a session; default: the placeholder's company or the key's")
+        .option("--company <company>", "Company slug or uid (cmp_…); default: the placeholder's company or the key's")
         .option("--expires <minutes>", `Link lifetime in minutes, 1-${LIBRARY_LINK_MAX_MINUTES} (default ${LIBRARY_LINK_DEFAULT_MINUTES})`, (value) => Number(value))
         .option("--json", "Print machine-readable JSON")
         .action(async (target, options) => {
@@ -544,7 +624,13 @@ export function registerLibraryCommand(program) {
             const result = await runLibraryLink(target, { company: options.company, expiresMinutes: options.expires }, {
                 hqRoot: () => findHqRoot(),
                 apiKey: credential.kind === "api-key",
-                resolveCompany: (ref) => getCompanyUid(token, ref),
+                resolveCompany: credential.kind === "api-key"
+                    ? (ref, placeholderSlug) => libraryLinkCompanyForApiKey(ref, placeholderSlug, {
+                        manifest: manifestOrNull,
+                        envCompanyUid: process.env.HQ_COMPANY_UID?.trim() || undefined,
+                        fallback: () => getCompanyUid(token, undefined),
+                    })
+                    : (ref) => getCompanyUid(token, ref),
                 presign: (body) => vaultApiFetch({ token, path: "/v1/files/presign", method: "POST", body }),
             });
             // The URL is the only stdout line (or the JSON), so scripts can capture it.
@@ -557,5 +643,6 @@ export function registerLibraryCommand(program) {
             process.exitCode = 1;
         }
     });
+    registerLibraryRemoveCommand(library);
 }
 //# sourceMappingURL=library.js.map

package/dist/commands/secrets.js

@@ -4,6 +4,7 @@ import * as yaml from "js-yaml";
 import { assertApiKeyCompany, buildSecretUsage, extractApiMessage, highSecuritySandboxOnlyMessage, loadRevealedSecrets, normalizeScriptLockMode, normalizeSecretTier, parseSecretNameList, requestedApiKeyCompany, runSecretsEnvCommand, scopeOpts, secretsCredentialOptions, } from "../secrets-env-action.js";
 import { readSessionCompanyLock } from "../lib/session-company-lock.js";
 import { sessionIdFromEnv } from "../lib/core-utils/session-id.js";
+import { appendPersonalSecretsAudit, isEntityScopeRef, PERSONAL_SCOPE_READ_ONLY_MESSAGE, } from "../lib/personal-secrets-audit.js";
 export { readSessionCompanyLock } from "../lib/session-company-lock.js";
 export { buildSecretUsage, emitEnvExportsAndExit, loadRevealedSecrets, parseSecretNameList, runSecretsEnvCommand, } from "../secrets-env-action.js";
 function companyUidForSlug(root, slug) {
@@ -53,7 +54,7 @@ async function resolveApiKeyCompanyWithinLock(input) {
     throw new Error("HQ_API_KEY is not bound to a company in this session's locked company set.");
 }
 import chalk from "chalk";
-import { ensureCognitoToken } from "../utils/cognito-session.js";
+import { cognitoSubjectFromToken, ensureCognitoToken } from "../utils/cognito-session.js";
 /**
  * Exit code for `hq secrets exec` run with no session id and no explicit
  * company. 78 is EX_CONFIG from sysexits.h: the caller's invocation is missing
@@ -508,6 +509,35 @@ export function registerSecretsCommand(program) {
         .description("Manage secrets in HQ vault (SSM Parameter Store)")
         .option("--company <slug>", "Company slug (resolves to companyUid)")
         .option("--personal", "Operate on the caller's personal vault (no sharing)");
+    // In a session locked to a company, the caller's personal vault is read-only
+    // and reachable only through `secrets exec` (which audit-logs each use).
+    // Writes, sharing, listing and printing values stay refused.
+    secrets.hook("preAction", async (_parent, actionCommand) => {
+        if (actionCommand.parent === secrets && actionCommand.name() === "exec")
+            return;
+        const parentOpts = secrets.opts();
+        const actionOpts = actionCommand.opts();
+        const companyRef = actionOpts.company ?? parentOpts.company ?? process.env.HQ_COMPANY_UID?.trim();
+        // --company prs_…/agt_… names a personal vault: same read-only rule.
+        const personal = Boolean(parentOpts.personal) || Boolean(actionOpts.personal)
+            || (companyRef !== undefined && isEntityScopeRef(companyRef));
+        if (!personal || !sessionIdFromEnv(process.env))
+            return;
+        if (!(await fastFlagEnabledDefaultOn(MULTI_COMPANY_SESSION_LOCK_FLAG)))
+            return;
+        let lock;
+        try {
+            lock = readSessionCompanyLock(process.env);
+        }
+        catch (err) {
+            console.error(chalk.red("Error:"), err instanceof Error ? err.message : String(err));
+            process.exit(1);
+        }
+        if (!lock || lock.companies.length === 0 || lock.companies.includes("personal"))
+            return;
+        console.error(chalk.red("Error:"), PERSONAL_SCOPE_READ_ONLY_MESSAGE);
+        process.exit(1);
+    });
     secrets
         .command("set <name>")
         .description("Create or update a secret")
@@ -1181,9 +1211,9 @@ export function registerSecretsCommand(program) {
                 process.exit(1);
             }
             const keys = parseSecretNameList(_opts.only);
-            const parentScope = secrets.opts();
+            const parentScope = { ...secrets.opts() };
             const inheritedCompany = parentScope.company;
-            const requestedCompany = _opts.company ?? inheritedCompany;
+            let requestedCompany = _opts.company ?? inheritedCompany;
             // A launchd or cron job has no session id. Session resolution would then
             // fall back to workspace/sessions/.current, which names whichever
             // interactive session last ran a hook, and the job would read that
@@ -1200,6 +1230,17 @@ export function registerSecretsCommand(program) {
             const sessionLock = multiCompanyLockEnabled && hasCallerSession ? readSessionCompanyLock(process.env) : undefined;
             const hasLockedCompanies = (sessionLock?.companies.length ?? 0) > 0;
             const lockRoot = hasLockedCompanies ? resolveDefaultHqRoot({ env: process.env }) : undefined;
+            // A prs_/agt_ value passed as --company names a personal vault. In a
+            // locked session it gets exactly the --personal rules: one locked
+            // company, exec only, the caller's own uid only, and the audit line.
+            const entityScopeRef = hasLockedCompanies && requestedCompany && isEntityScopeRef(requestedCompany)
+                ? requestedCompany
+                : undefined;
+            if (entityScopeRef) {
+                requestedCompany = undefined;
+                delete parentScope.company;
+                parentScope.personal = true;
+            }
             const selectedCompany = (hasLockedCompanies && requestedCompany && looksLikeCompanyUid(requestedCompany)
                 ? companySlugForUid(lockRoot, sessionLock.companies, requestedCompany) ?? requestedCompany
                 : requestedCompany)
@@ -1207,8 +1248,14 @@ export function registerSecretsCommand(program) {
             if (hasLockedCompanies && selectedCompany && !sessionLock.companies.includes(selectedCompany)) {
                 throw new Error(`Company '${selectedCompany}' is outside this session's locked company set.`);
             }
-            if (hasLockedCompanies && parentScope.personal && !sessionLock.companies.includes("personal")) {
-                throw new Error("Personal scope is outside this session's locked company set.");
+            // Owner decision dq_20261020234444_f1b1ea4185: the caller's own personal
+            // vault may be read next to exactly one locked company, through exec
+            // only, and every use is audit-logged below.
+            const personalNextToCompany = hasLockedCompanies
+                && Boolean(parentScope.personal)
+                && !sessionLock.companies.includes("personal");
+            if (personalNextToCompany && sessionLock.companies.length !== 1) {
+                throw new Error(`Personal scope can be read next to exactly one locked company; this session locks ${sessionLock.companies.length}.`);
             }
             if (hasLockedCompanies && !selectedCompany && !parentScope.personal) {
                 throw new Error("This session has no locked company scope for secrets exec.");
@@ -1220,6 +1267,9 @@ export function registerSecretsCommand(program) {
                 ? scopeOpts({ personal: true })
                 : scopeOpts({ ...parentScope, ...(selectedCompany ? { company: selectedCompany } : {}) });
             const cred = await resolveVaultCredentialForCapability("secrets:read", "secrets exec", secretsCredentialOptions());
+            if ((personalNextToCompany || entityScopeRef) && cred.kind !== "cognito") {
+                throw new Error("Personal scope in a company-locked session needs your own HQ sign-in, not an API key.");
+            }
             const apiKeyCompany = cred.kind === "api-key" && hasLockedCompanies
                 ? await resolveApiKeyCompanyWithinLock({
                     token: cred.token,
@@ -1240,6 +1290,23 @@ export function registerSecretsCommand(program) {
                         ? await assertApiKeyCompany(cred.token, unlockedApiKeyCompanyRef, "secrets exec")
                         : "__api_key__"))
                 : await getEntityUid(cred.token, secretScope, { allowOfflineScopeFallback: true });
+            if (entityScopeRef && companyUid !== entityScopeRef) {
+                throw new Error("Another person's personal vault is outside this session's scope; refusing.");
+            }
+            if (personalNextToCompany) {
+                // Only the caller's own scope: getEntityUid({ personal }) resolves the
+                // token's own entity. Refuse anything that is not a person/agent-self
+                // uid, or that disagrees with the token's entity claim.
+                const claimedUid = cognitoSubjectFromToken(cred.token).entityUid;
+                if (!/^(prs|agt)_/.test(companyUid) || (claimedUid && claimedUid !== companyUid)) {
+                    throw new Error("Personal scope did not resolve to your own vault; refusing.");
+                }
+                appendPersonalSecretsAudit(lockRoot, {
+                    session_id: sessionLock.sessionId,
+                    locked_company: sessionLock.companies[0],
+                    secret_names: keys,
+                });
+            }
             const readSecrets = async () => loadRevealedSecrets(cred.token, companyUid, keys, cred.kind === "cognito"
                 ? await buildSecretUsage("exec", _opts.script, _opts.scriptId)
                 : undefined, { allowOfflineFallback: true });

package/dist/commands/storage-offload.d.ts

@@ -23,7 +23,10 @@
  *         recorded in the sync journal as synced and cloud-only, then the
  *         placeholder is written, then the local file is removed. A path the
  *         sync ignore rules exclude is refused and the excluding rule is named
- *         (for `.hqinclude`, with the exact line to add). Other unsynced
+ *         (for `.hqinclude`, with the exact line to add). A library original
+ *         restored by `hq library fetch`, which the journal does not know, is
+ *         pointed back at its verified blob `.hq-offload/blobs/<sha256>` in the
+ *         company vault (`point-at-library`), uploading nothing. Other unsynced
  *         company files are skipped with "run hq sync first".
  *       - Any other file points at its personal-vault sync object the same
  *         way, or is uploaded to the personal vault's `.hq-offload/blobs/`.
@@ -65,6 +68,12 @@ export declare const RUN_SYNC_FIRST = "run hq sync first";
 export declare const SYNC_MAX_FILE_BYTES: number;
 /** Object metadata key holding the sha256 of a company-vault offload upload. */
 export declare const VAULT_SHA256_METADATA_KEY = "hq-sha256";
+/**
+ * Object metadata key on library blobs (`hq library add`). hq-pro's put
+ * presign binds it to the `x-amz-checksum-sha256` it signs, and S3 checks that
+ * checksum against the bytes, so it is the stored bytes' sha256.
+ */
+export declare const CONTENT_SHA256_METADATA_KEY = "hq-content-sha256";
 /** Top-level HQ-root folder that holds offloaded blobs in the personal vault. */
 export declare const OFFLOAD_TOP_LEVEL = ".hq-offload";
 /**
@@ -197,11 +206,13 @@ export interface VaultObjectStore {
     /**
      * Size and unquoted ETag of `key`, or null when it is not there. `sha256` is
      * the object's `hq-sha256` metadata, set on company-vault offload uploads.
+     * `contentSha256` is its `hq-content-sha256` metadata, set on library blobs.
      */
     head(key: string): Promise<{
         size: number;
         etag: string;
         sha256?: string;
+        contentSha256?: string;
     } | null>;
     /** Download `key` to `dest` only if its ETag is `etag`; returns the served ETag. */
     download(key: string, dest: string, etag: string): Promise<string>;
@@ -403,10 +414,17 @@ export interface CurrentFilePlan {
     /**
      * upload+offload: a company file over the sync limit, uploaded to the
      * company vault at `vault_key`, then replaced by a placeholder.
+     * point-at-library: a restored library original whose verified blob is
+     * already in the company vault at `vault_key`; nothing is uploaded.
      */
-    action: "point-at-vault" | "upload" | "upload+offload" | "skip";
-    /** Company vault key for upload+offload. */
+    action: "point-at-vault" | "upload" | "upload+offload" | "point-at-library" | "skip";
+    /** Company vault key for upload+offload and point-at-library. */
     vault_key?: string;
+    /**
+     * point-at-library only: "kept" when the library placeholder already sits
+     * beside the file (it is left as is), "written" when offload writes it.
+     */
+    placeholder?: "kept" | "written";
     /** The HQ sync ignore layer that excludes this path. */
     excluded_by?: string;
     reason?: string;
@@ -416,7 +434,7 @@ export interface CurrentOffloaded {
     bytes: number;
     vault: "personal" | "company";
     company?: string;
-    action: "point-at-vault" | "upload" | "upload+offload";
+    action: "point-at-vault" | "upload" | "upload+offload" | "point-at-library";
 }
 export interface OffloadOptions {
     minBytes: number;