@hasna/skills 0.1.63 → 0.1.64

package/dist/lib/agent-sync.d.ts

@@ -56,6 +56,18 @@ export declare function agentGlobalSkillsDir(agent: SyncAgent, homeDir?: string)
  * would corrupt meaning, and corpus/instruction skills are authored tool-neutral.
  */
 export declare function adaptSkillMdForAgent(skillMd: string, agent: string): string;
+/**
+ * The sentence every sync pointer stub carries in its body. It survives per-agent
+ * adaptation (adaptSkillMdForAgent only touches `user_invocable`), so it is the stable
+ * fingerprint for "this document is a pointer, not the skill's real content".
+ */
+export declare const POINTER_MARKER_PHRASE = "This is an executable skill from the @hasna/skills catalog";
+/**
+ * True when a SKILL.md is a sync pointer stub: frontmatter declares `kind: executable`
+ * AND the body carries the canonical pointer sentence. A full content document is never
+ * a stub even when it mentions the sentence, because it lacks the kind marker.
+ */
+export declare function isPointerSkillMd(markdown: string): boolean;
 /** A pointer SKILL.md for an executable skill: what it is and how to actually run it. */
 export declare function pointerSkillMd(name: string, description: string): string;
 export type SyncActionKind = "create" | "update" | "skip";
@@ -81,8 +93,12 @@ export interface SyncSkillsOptions {
     rootDir?: string;
     /**
      * Explicit canonical-corpus source: a directory of skill folders, or the monorepo
-     * package root (which contains `skills/` and `agent-skills/`). Takes precedence over
+     * package root (which contains `skills/`). Takes precedence over
      * $SKILLS_SOURCE, which takes precedence over the installed corpus cache.
+     * Agent-workflow skills are NOT part of the public repo corpus anymore — they
+     * moved to the private per-station store (hasna-internal/fleet-resources) and
+     * reach sync through the installed cache — so a package root resolves to
+     * `skills/` only.
      */
     sourceDir?: string;
     /** Home directory override for agent skill dirs. Tests only. */
@@ -96,11 +112,13 @@ export interface SyncSkillsResult {
  *
  * The package ships no bundled corpus. Precedence is explicit-over-ambient:
  *   1. `options.sourceDir`   - an explicit source: a corpus dir, or a package root
- *                              containing `skills/` and/or `agent-skills/`
+ *                              containing `skills/`
  *   2. `$SKILLS_SOURCE`      - the ambient spelling of the same thing
  *   3. the installed cache   - `getPortableSkillsRoot()` (what `skills pull` writes),
  *      resolved through `resolveCorpusRoot` so a migrated owner layout
- *      (~/.hasna/skills/skills/) is read in preference to `installed/`.
+ *      (~/.hasna/skills/skills/) is read in preference to `installed/`. This cache is
+ *      also where private agent-workflow skills arrive from the per-station store
+ *      (hasna-internal/fleet-resources) and get synced into agent folders.
  *
  * A missing explicit source is an error, not a fallback to "nothing": the whole point
  * of zero-corpus is that sync must not silently sync an empty corpus because the
@@ -125,9 +143,11 @@ export interface WriteManagedAgentSkillParams {
  * Write one skill into one agent's global folder, non-clobbering.
  *
  * A directory this tool has written before carries the marker file and is replaced with
- * an exact mirror. A directory with a SKILL.md but no marker is the user's own skill and
- * is skipped unless `force` explicitly adopts it. Any other pre-existing unmarked
- * directory is always left untouched. A fresh directory is created.
+ * an exact mirror — except that a managed home holding full content is never silently
+ * replaced with an executable pointer stub (that would be data loss; it is refused
+ * unless `force` is passed). A directory with a SKILL.md but no marker is the user's
+ * own skill and is skipped unless `force` explicitly adopts it. Any other pre-existing
+ * unmarked directory is always left untouched. A fresh directory is created.
  */
 export declare function writeManagedAgentSkill(params: WriteManagedAgentSkillParams): AgentSyncAction;
 export interface ManagedDirWriteResult {

package/dist/lib/auth-store.d.ts

@@ -1,3 +1,30 @@
+/**
+ * auth.json lives at the skills app root, beside config.json.
+ *
+ * Resolved through getDataDir() so that $HASNA_SKILLS_DIR relocates the
+ * credential file along with the rest of the app's state. It used to be an
+ * import-time constant composed from homedir(), so with the override set the
+ * CLI stored its API key at ~/.hasna/skills/auth.json while config, corpus,
+ * and database all moved — the same override-only-half-works split getDataDir()
+ * documents for its own history.
+ *
+ * The legacy ~/.skills/auth.json stays a $HOME concern, exactly like
+ * getDataDir()'s legacy merge (which is deliberately skipped for an overridden
+ * dir): it is still read as a fallback and removed by clearAuthConfig(), but
+ * never written when the override is set. Like getDataDir(), the home is read
+ * from the environment at call time — os.homedir() caches its answer after the
+ * first call, so a process that re-points $HOME would keep composing the old
+ * path.
+ */
+export declare function getAuthFilePath(): string;
+/**
+ * Write-free credential path resolution for read-only paths (e.g. `sync --dry-run`).
+ *
+ * getAuthFilePath() routes through getDataDir(), which WRITES (mkdirs the app dir,
+ * merges legacy ~/.skills content, copies the legacy config). A dry run must read
+ * the same credential file a real run would without performing any of that.
+ */
+export declare function getAuthFilePathReadOnly(): string;
 /**
  * Stored credentials for a Skills API instance.
  *
@@ -18,6 +45,16 @@ export declare function getAuthConfig(): AuthConfig | null;
 export declare function saveAuthConfig(config: AuthConfig): void;
 export declare function clearAuthConfig(): void;
 export declare function getApiKey(): string | null;
+/**
+ * Write-free credential read for read-only paths (e.g. `sync --dry-run`).
+ *
+ * getAuthConfig() resolves through getAuthFilePath() -> getDataDir(), which
+ * writes. Reads the same files (canonical auth.json, then the legacy ~/.skills
+ * fallback) without creating or migrating anything, and without touching the
+ * write path's module-level cache.
+ */
+export declare function getAuthConfigReadOnly(): AuthConfig | null;
+export declare function getApiKeyReadOnly(): string | null;
 export declare function normalizeSkillsApiOrigin(apiUrl: string): string;
 /**
  * Origin every credential-bearing request is sent to.

package/dist/lib/config.d.ts

@@ -58,12 +58,63 @@ export declare const DATA_DIR_ENV = "HASNA_SKILLS_DIR";
  * `custom` without colliding with anything.
  */
 export declare const INSTALLED_SKILLS_DIRNAME = "installed";
+/**
+ * Subfolder of the data directory holding the migrated corpus cache — the
+ * owner-layout replacement for installed/ after `skills storage migrate`
+ * (~/.hasna/skills/{skills,logs,outputs}).
+ *
+ * The marker file inside it (LAYOUT_MIGRATION_RECORD) is the authority: a
+ * skills/ directory someone created by hand is not the corpus and never will
+ * be treated as one (see isOwnerLayoutMigrated).
+ */
+export declare const SKILLS_CACHE_DIRNAME = "skills";
+/**
+ * Marker file inside the corpus cache proving the owner-layout migration ran;
+ * also its record (see migrateOwnerLayout in home-migration.ts).
+ */
+export declare const LAYOUT_MIGRATION_RECORD = ".layout-migration.json";
+/**
+ * True once the owner layout has been migrated (the record is the authority).
+ *
+ * Lives here — rather than in home-migration.ts — because the canonical corpus
+ * resolver in portable-skills.ts must consult it too, and home-migration.ts
+ * depends on portable-skills.ts; this module sits below both.
+ */
+export declare function isOwnerLayoutMigrated(appDir: string): boolean;
 /**
  * Get the data directory for skills global config/data.
  * Default: ~/.hasna/skills/, overridable with $HASNA_SKILLS_DIR.
  * Auto-migrates from ~/.skills/ and ~/.skillsrc without deleting legacy data.
  */
 export declare function getDataDir(): string;
+/**
+ * Write-free data-dir resolution for read-only paths (e.g. `sync --dry-run`).
+ *
+ * getDataDir() itself writes: it mkdirs the app folder, merges legacy ~/.skills
+ * content and copies the legacy config file. A dry run must resolve the SAME
+ * directory a real run would use without performing any of that — mirror the path
+ * logic only, reading $HASNA_SKILLS_DIR and $HOME exactly the way getDataDir does.
+ */
+export declare function getDataDirReadOnly(): string;
+/**
+ * Get the config file path for a given scope, write-free (see getDataDirReadOnly).
+ */
+export declare function getConfigPathReadOnly(scope: ConfigScope): string;
+/**
+ * Load merged config (project-local overrides global) without the writes
+ * getDataDir() performs on the write path.
+ *
+ * The write path folds the legacy ~/.skillsrc into canonical config.json as part of
+ * getDataDir()'s migration — copied ONLY when canonical config.json is absent, and
+ * the legacy migration is skipped entirely when a data-directory override is active.
+ * This mirrors that FILE-LEVEL precedence, never field-level merging: canonical
+ * config.json, when present, is the whole global config; legacy ~/.skillsrc is read
+ * only in the exact situation the write path would copy it (no canonical file, no
+ * override). Field-level merging would inherit a stale legacy origin beneath a
+ * canonical config that omits apiUrl — and the client sends its stored credential to
+ * whatever origin resolves, so divergence from the write path is credential-bearing.
+ */
+export declare function loadConfigReadOnly(): SkillsConfig;
 /**
  * Get the config file path for a given scope
  */

package/dist/lib/home-census.d.ts

@@ -8,6 +8,10 @@ export interface DriftEntry {
     path: string;
     homeHash?: string;
     canonicalHash?: string;
+    /** True when the home's SKILL.md is a sync pointer stub rather than real content. */
+    homeStub?: boolean;
+    /** True when the canonical corpus entry renders as a pointer stub (executable skill). */
+    canonicalStub?: boolean;
 }
 export interface DriftCensus {
     entries: DriftEntry[];

package/dist/lib/home-migration.d.ts

@@ -1,10 +1,7 @@
 import { type PortableSkillOptions } from "./portable-skills.js";
-/** The canonical corpus cache subfolder of the app folder. */
-export declare const SKILLS_CACHE_DIRNAME = "skills";
+export { LAYOUT_MIGRATION_RECORD, SKILLS_CACHE_DIRNAME, isOwnerLayoutMigrated } from "./config.js";
 export declare const LOGS_DIRNAME = "logs";
 export declare const OUTPUTS_DIRNAME = "outputs";
-/** Marker file inside skills/ proving a migration ran; also its record. */
-export declare const LAYOUT_MIGRATION_RECORD = ".layout-migration.json";
 export declare const LEGACY_CUSTOM_DIRNAME = "custom";
 export interface LayoutMigrationRecord {
     version: 1;
@@ -15,19 +12,21 @@ export interface LayoutMigrationRecord {
     note: string;
 }
 export declare function layoutMigrationRecordPath(appDir: string): string;
-/** True once the owner layout has been migrated (the record is the authority). */
-export declare function isOwnerLayoutMigrated(appDir: string): boolean;
 /**
  * Resolve the corpus the sync/fan-out reads from.
  *
- * Precedence:
+ * The precedence lives in ONE place, getPortableSkillsRoot():
  *   1. options.rootDir — named outright, no suffix (unchanged contract)
  *   2. migrated owner layout — <app folder>/skills when a migration record exists
- *   3. the pre-migration corpus — getPortableSkillsRoot() (installed/, with the
- *      legacy auto-copy migration)
+ *   3. the pre-migration corpus — installed/, with the legacy auto-copy migration
  *
  * The migration record is required: a skills/ directory someone created by hand
  * is not the corpus and never will be treated as one.
+ *
+ * This wrapper exists so pull/agent-sync and any future caller can name the
+ * canonical resolver explicitly; delegating keeps a single implementation for
+ * list/search/info/push/sync alike (bug 170b0e9b was exactly the opposite — a
+ * second resolution that read installed/ while this one read skills/).
  */
 export declare function resolveCorpusRoot(options?: PortableSkillOptions): string;
 export type LayoutMigrationStatus = "already-migrated" | "refused" | "migrated" | "nothing-to-do";

package/dist/lib/native-storage.d.ts

@@ -94,7 +94,7 @@ export declare function getStorageDatabaseEnv(env?: Record<string, string | unde
 export declare function getSkillsStorageDatabaseUrl(env?: Record<string, string | undefined>): string | undefined;
 export declare function getStorageDatabaseUrl(env?: Record<string, string | undefined>): string | undefined;
 export interface SkillsNativeStorageStatus {
-    package: "open-skills";
+    package: "skills";
     tables: readonly SkillsStorageTable[];
     env: {
         databaseUrl: string;

package/dist/lib/portable-skills.d.ts

@@ -7,11 +7,21 @@ export * from "./portable-skills-types.js";
 /**
  * Resolve the corpus: the directory holding one folder per installed skill.
  *
+ * THIS IS THE ONE CANONICAL CORPUS RESOLUTION. Every local discovery and
+ * publish path — list, search, info, push, pull, sync, registry — reads the
+ * corpus through this function (directly or via resolveCorpusRoot(), which
+ * delegates here), so a migrated owner layout is never bypassed by a path that
+ * still resolves installed/ (bug 170b0e9b: 'skills list --all' returned 87
+ * entries while the migrated corpus held 688).
+ *
  * Precedence is explicit-over-ambient, most specific first:
- *   1. `options.rootDir`  - the corpus, named outright (no `installed` suffix)
- *   2. `options.homeDir`  - <home>/.hasna/skills/installed
- *   3. `getDataDir()`     - <app folder>/installed, where the app folder is
- *                           $HASNA_SKILLS_DIR, else ~/.hasna/skills
+ *   1. `options.rootDir`      - the corpus, named outright (no suffix)
+ *   2. the migrated owner layout - <app folder>/skills/ when a migration record
+ *      exists there (the record is the authority; a skills/ directory someone
+ *      created by hand is not the corpus)
+ *   3. `getDataDir()`         - <app folder>/installed (pre-migration corpus,
+ *      with the legacy auto-copy migration), where the app folder is
+ *      $HASNA_SKILLS_DIR, else ~/.hasna/skills
  *
  * The app folder holds app data (config.json, skills.db, auth.json); the corpus
  * is a named subfolder of it, matching every sibling Hasna app. One variable
@@ -46,6 +56,24 @@ export interface CorpusSkillMeta {
     tags?: string[];
     version?: string;
     kind?: SkillKind;
+    /**
+     * The hosted registry's revision id for this skill (todos d061fcda), when the
+     * instance reported one. Carried onto the metadata-only pull path so the pull marker
+     * records which revision was installed there too.
+     */
+    revisionId?: string;
+    /**
+     * The row's SKILL.md, served in the published metadata so a client can recompute the
+     * content-addressed revision id and PROVE the declared revision identifies the content
+     * it received (todos d061fcda).
+     */
+    skillMd?: string;
+    /**
+     * The row's stored source (the payload's own `source` is always the client view
+     * "remote"). The canonical revision hash is computed over the stored value, so the
+     * client needs it to recompute the id.
+     */
+    publishedSource?: string;
 }
 export interface WriteCorpusSkillInput {
     name: string;
@@ -54,8 +82,9 @@ export interface WriteCorpusSkillInput {
     meta?: CorpusSkillMeta | null;
 }
 /**
- * Write a skill fetched from a Skills instance into the local corpus
- * (~/.hasna/skills/installed/<name>/), so loadRegistry() surfaces it to both the CLI
+ * Write a skill fetched from a Skills instance into the local corpus (the
+ * canonical root — installed/ before the layout migration, <app folder>/skills/
+ * after it), so loadRegistry() surfaces it to both the CLI
  * (`skills list --all`) and the MCP (`list_skills`) with no further step — the whole
  * point of the pull: the corpus is already a first-class registry source.
  *

package/dist/lib/pull.d.ts

@@ -5,6 +5,10 @@ import type { SkillKind } from "./registry-types.js";
 export declare const BUNDLE_DIGEST_HEADER = "X-Skill-Bundle-Sha256";
 /** Header carrying the HMAC signature of the served bundle, when the server can sign. */
 export declare const BUNDLE_SIGNATURE_HEADER = "X-Skill-Bundle-Signature";
+/** Header carrying the immutable revision identity of the served row (todos d061fcda). */
+export declare const BUNDLE_REVISION_ID_HEADER = "X-Skill-Revision-Id";
+/** Header carrying the per-slug write counter of the served row. */
+export declare const BUNDLE_REVISION_NUMBER_HEADER = "X-Skill-Revision-Number";
 /** Marker file written inside each corpus skill directory recording pull provenance. */
 export declare const PULL_MARKER_FILE = ".hasna-skills.json";
 /**
@@ -48,6 +52,26 @@ export interface PulledSkillResult {
     sourceCommit?: string;
     /** True when the pull created the corpus entry, false when it updated an existing one. */
     created?: boolean;
+    /**
+     * The revision id (todos d061fcda) this pull installed, when the instance reported one.
+     * Recorded in the marker so a later pull can detect that the remote moved on.
+     */
+    revisionId?: string;
+    /** True when the instance answered 410: the slug was deleted and pull reconciled. */
+    tombstoned?: boolean;
+    /** With `tombstoned`: true when a local corpus entry existed and was removed. */
+    removed?: boolean;
+    /**
+     * With `tombstoned`: true when the local corpus entry was NOT pull-managed (no pull
+     * marker), so it was left in place — a remote 410 never deletes a user-created skill.
+     */
+    leftInPlace?: boolean;
+    /**
+     * True when the instance no longer serves a published revision under this slug (its
+     * tombstone window expired) but the local copy is a revision-marked published install.
+     * Reported instead of silently swapping in a bundled skill of the same name.
+     */
+    purged?: boolean;
     error?: string;
 }
 export interface PullSkillsResult {
@@ -66,6 +90,10 @@ export interface VerifiedBundle {
     serverHash?: string;
     /** The server-declared signature, when the header was present. */
     signature?: string;
+    /** The server-declared revision id, when the header was present and well-formed. */
+    revisionId?: string;
+    /** The server-declared per-slug write counter, when the header was present. */
+    revisionNumber?: number;
 }
 export declare function pullSkills(options?: PullSkillsOptions): Promise<PullSkillsResult>;
 /**
@@ -89,6 +117,7 @@ export declare function installBundleAtomically(name: string, entries: SkillBund
     contentHash?: string;
     sourceCommit?: string;
     signature?: string;
+    revisionId?: string;
 }): {
     path: string;
     created: boolean;
@@ -104,4 +133,6 @@ export declare function writePullMarker(dir: string, record: {
     contentHash?: string;
     sourceCommit?: string;
     signature?: string;
+    revisionId?: string;
+    source?: "pull" | "sync";
 }): void;

package/dist/lib/registry-reconcile.d.ts

@@ -0,0 +1,114 @@
+import { type PortableSkillOptions } from "./portable-skills.js";
+import { RemoteSkillsClient } from "./remote-client.js";
+export type ReconcileConflictPolicy = "local" | "remote" | "skip";
+/**
+ * The default policy, named exactly as the plan specifies: when the digests are identical
+ * the local state wins by construction (nothing to resolve); every other divergence is
+ * skipped and reported unless --conflict says otherwise.
+ */
+export declare const DEFAULT_CONFLICT_POLICY: "local-wins-on-identical-digest-else-skip-and-report";
+export declare const CONFLICT_POLICIES: readonly ReconcileConflictPolicy[];
+/** Corpus-root cursor recording the last sync run. */
+export declare const SYNC_CURSOR_FILE = ".sync-cursor.json";
+export declare const SYNC_CURSOR_SCHEMA_VERSION: 1;
+export interface ReconcileRegistryOptions extends PortableSkillOptions {
+    /** Push local-only, changed-locally, and conflicts won by local. */
+    push?: boolean;
+    /** Pull remote-only, changed-remotely, and conflicts won by remote. */
+    pull?: boolean;
+    /** Both directions (the default when neither --push nor --pull is given). */
+    all?: boolean;
+    /** Plan and report without writing anything. */
+    dryRun?: boolean;
+    /** Conflict resolution policy. */
+    conflict?: ReconcileConflictPolicy;
+    /** Client override. `undefined` resolves one from configuration; `null` models "no credential". */
+    client?: RemoteSkillsClient | null;
+    /** HMAC signing key for bundle signature verification. Defaults to $SKILLS_SIGNING_KEY. */
+    signingKey?: string;
+}
+export type ReconcileSkillState = "local-only" | "remote-only" | "changed-locally" | "changed-remotely" | "conflict" | "in-sync";
+export type ReconcileAction = "push" | "pull" | "skip" | "none";
+export interface ReconcileSkillEntry {
+    slug: string;
+    state: ReconcileSkillState;
+    action: ReconcileAction;
+    localVersion?: string;
+    remoteVersion?: string;
+    localSha256?: string;
+    remoteSha256?: string;
+    /** Why the entry was classified or skipped this way. */
+    reason?: string;
+    /** Present only for executed (non-dry-run) actions. */
+    result?: {
+        ok: boolean;
+        detail?: string;
+    };
+}
+export interface ReconcileSummary {
+    /** Skills found in the local corpus. */
+    local: number;
+    /** Skills the registry serves (published plus bundled). */
+    remote: number;
+    inSync: number;
+    pushed: number;
+    pulled: number;
+    /** Divergences the conflict policy had to resolve (or decline to resolve). */
+    conflicts: number;
+    /** Divergences skipped under the policy. */
+    skipped: number;
+    errors: number;
+}
+export interface ReconcileCursor {
+    schemaVersion: typeof SYNC_CURSOR_SCHEMA_VERSION;
+    managedBy: string;
+    lastSyncedAt: string;
+    runCount: number;
+    summary: ReconcileSummary;
+}
+export interface ReconcileRegistryResult {
+    corpusRoot: string;
+    /** True when a real run would first migrate the legacy corpus layout into place. */
+    migrationPending: boolean;
+    direction: "push" | "pull" | "all";
+    dryRun: boolean;
+    conflictPolicy: ReconcileConflictPolicy;
+    /** The full declared policy label; identical to conflictPolicy for local/remote. */
+    conflictPolicyDescription: string;
+    summary: ReconcileSummary;
+    skills: ReconcileSkillEntry[];
+    /** Present only when the run was real and completed without errors. */
+    cursor?: Pick<ReconcileCursor, "lastSyncedAt" | "runCount">;
+}
+export declare class ReconcileRegistryError extends Error {
+    readonly detail?: string[] | undefined;
+    constructor(message: string, detail?: string[] | undefined);
+}
+/**
+ * Re-check the local side of one pull candidate, immediately before the pull batch.
+ *
+ * Packs FIRST, then samples existence: a directory that appeared between the plan and
+ * the pack is provably on disk when the sample runs. Sampling before the pack let a
+ * concurrent editor's partial tree read as "still absent" — the pack then threw on it
+ * while the stale sample stayed false, so localMoved was false and the pull replaced
+ * the newly created directory (review P1). The ops seam exists so a test can pin that
+ * ordering deterministically: pack throws on the partial tree, the post-pack sample
+ * sees it, and the candidate counts as moved.
+ *
+ * Returns true when the local side moved since the plan: a digest different from the
+ * planned one, or a directory present where the plan saw none (a concurrent editor).
+ */
+export declare function recheckLocalSide(plannedLocal: string | undefined, localDir: string, ops?: {
+    pack: (dir: string) => string;
+    exists: (dir: string) => boolean;
+}): boolean;
+/**
+ * Run one sync pass.
+ *
+ * The plan (classification + per-skill action) is computed in full before anything is
+ * executed, and a dry run stops at the plan: no publish, no pull, no marker, no cursor —
+ * proven by readback in the tests. Every executed mutation re-checks both sides first
+ * (see the module header); a side that moved since the plan skips that skill and reports
+ * it rather than overwriting state the plan did not see.
+ */
+export declare function reconcileRegistry(options?: ReconcileRegistryOptions): Promise<ReconcileRegistryResult>;

package/dist/lib/registry.d.ts

@@ -9,12 +9,15 @@ export declare function isBasicSkillName(name: string): boolean;
 export declare function findExtensionSkillPath(name: string): string | null;
 /**
  * Load the full registry: official skills merged with a configured private
- * extension checkout and global custom skills from ~/.hasna/skills/installed/<name>/
- * (plus the legacy ~/.hasna/skills/custom/<name>/ migration safety net).
+ * extension checkout and global custom skills from the canonical local corpus
+ * — <app folder>/installed/<name>/ before the owner-layout migration, <app
+ * folder>/skills/<name>/ after it (resolveCorpusRoot(), the one resolution
+ * every discovery path shares) — plus the legacy ~/.hasna/skills/custom/<name>/
+ * migration safety net.
  *
  * Custom skills take precedence over extensions, which take precedence over
- * official skills. Extension skills are read in place and never copied into installed/.
- * Results are cached for 5 seconds.
+ * official skills. Extension skills are read in place and never copied into the
+ * corpus. Results are cached for 5 seconds.
  */
 export declare function loadRegistry(cwd?: string): SkillMeta[];
 export declare function loadBasicRegistry(cwd?: string): SkillMeta[];

package/dist/lib/remote-client.d.ts

@@ -1,12 +1,83 @@
 import { type RemoteSkillRunContract } from "./remote-run-contract.js";
+/**
+ * A server that predates this client's pin/tag/incremental-sync routes answered
+ * 404/405 for them. The caller must never mistake that for "no pins" or "empty
+ * listing" — a silently-empty sync would look like success and drop nothing on
+ * the next push. This error is how the version-skew surfaces fail-closed.
+ */
+export declare class RemoteRouteUnsupportedError extends Error {
+    readonly path: string;
+    readonly status: number;
+    readonly instance: string;
+    constructor(path: string, status: number, instance: string);
+}
+/** Any other non-ok response on the new-route methods, with the status attached. */
+export declare class RemoteRequestError extends Error {
+    readonly path: string;
+    readonly status: number;
+    constructor(path: string, status: number, statusText: string);
+}
+/**
+ * A remote pin on a skill, matching the hosted-pins wire shape
+ * (`{ slug, pinnedAt, metadata }`). `pinnedAt`/`metadata` are server-reported
+ * and may be absent.
+ */
+export interface RemotePin {
+    slug: string;
+    pinnedAt?: string;
+    metadata?: Record<string, unknown>;
+}
+/** The minimal per-skill row the pin/tag/updated-since routes serve. */
+export interface RemoteSkillSummary {
+    slug: string;
+    name?: string;
+    version?: string;
+    updatedAt?: string;
+}
+/**
+ * One page of an incremental listing. `nextCursor` is an opaque continuation
+ * token; null (or an absent field) means the listing is complete.
+ */
+export interface UpdatedSincePage {
+    skills: RemoteSkillSummary[];
+    nextCursor: string | null;
+}
 export declare class RemoteSkillsClient {
     private apiUrl;
     private apiKey;
     constructor(apiKey: string, apiUrl?: string);
     private request;
+    /**
+     * Fail-closed version-skew guard for the pin/tag/updated-since routes.
+     *
+     * A server that predates these routes answers 404 (unmatched path) or 405
+     * (unmatched method). Both are surfaced as `RemoteRouteUnsupportedError` —
+     * never as an empty listing, which would read as "no pins / no changes" and
+     * silently desynchronize the caller. Every other non-ok response becomes a
+     * `RemoteRequestError` carrying the status.
+     *
+     * `domainNotFoundCodes` is the one deliberate exception: a route the server
+     * DOES have can 404 for a domain reason (the hosted-pins DELETE answers
+     * `{ code: "PIN_NOT_FOUND" }` when no pin exists). A 404 whose JSON body
+     * carries one of those codes is returned to the caller (status intact) so it
+     * can apply domain semantics instead of misreporting version skew. Every
+     * other 404 — including the dispatcher's `{ code: "NOT_FOUND" }` on a route
+     * the server lacks — still throws `RemoteRouteUnsupportedError`.
+     */
+    private requestNewRoute;
     listSkills(): Promise<any[]>;
     getSkillMd(slug: string): Promise<string | null>;
     getSkill(slug: string): Promise<any | null>;
+    /**
+     * Raw GET for one skill, with the HTTP status surfaced. Used by the reconcile
+     * re-check (registry-reconcile.ts) so it can distinguish "no such skill" (404) from
+     * "the registry failed to answer" (any other non-success status) instead of treating
+     * both as absent.
+     */
+    getSkillStatus(slug: string): Promise<{
+        status: number;
+        body: unknown;
+    }>;
     submitRun(slug: string, input?: Record<string, unknown>, args?: string[]): Promise<RemoteSkillRunContract>;
     getRun(runId: string): Promise<RemoteSkillRunContract | null>;
     getRunLogs(runId: string): Promise<any[]>;
@@ -24,8 +95,13 @@ export declare class RemoteSkillsClient {
      * Note the deliberate absence of `request()`: that helper pins
      * `Content-Type: application/json`, and a multipart body whose Content-Type does not
      * carry the generated boundary is unparseable at the other end.
+     *
+     * Optimistic concurrency (todos d061fcda): pass the revision id this client last read
+     * for the slug (from getSkill().revisionId) as `ifMatch`. The instance refuses a
+     * publish against a live slug that does not name its current revision with 409 — this
+     * is how a push never silently overwrites a newer remote revision.
      */
-    publishSkill(manifest: Record<string, unknown>, bundle?: Uint8Array): Promise<Response>;
+    publishSkill(manifest: Record<string, unknown>, bundle?: Uint8Array, ifMatch?: string): Promise<Response>;
     deleteSkill(slug: string): Promise<Response>;
     downloadSkillBundle(slug: string): Promise<Response>;
     /**
@@ -34,5 +110,46 @@ export declare class RemoteSkillsClient {
      * instance serves no bundle for this skill (the metadata-only fallback path).
      */
     getBundle(slug: string): Promise<Response | null>;
+    /** List the pins the instance holds for this principal. */
+    listPins(): Promise<RemotePin[]>;
+    /**
+     * Pin a skill on the instance (upsert — pinning again refreshes it). The
+     * wire contract matches the hosted-pins routes: a PUT with an optional
+     * `{ metadata }` body, answered with the stored pin (`slug`, `pinnedAt`,
+     * `metadata`).
+     */
+    pin(slug: string, metadata?: Record<string, unknown>): Promise<RemotePin>;
+    /**
+     * Unpin a skill on the instance. Resolves true when a pin existed and was
+     * deleted; false when the instance has no pin for this slug (its 404
+     * carries `code: "PIN_NOT_FOUND"` — a domain answer, not version skew). A
+     * bare 404 (route not deployed) still throws `RemoteRouteUnsupportedError`.
+     */
+    unpin(slug: string): Promise<boolean>;
+    /** List the tag names the instance serves. */
+    listTags(): Promise<string[]>;
+    /** List the skills carrying a tag on the instance. */
+    skillsByTag(tag: string): Promise<RemoteSkillSummary[]>;
+    /**
+     * Cursor-based incremental listing of skills updated after `since` (ISO 8601).
+     * Each page carries an opaque `nextCursor`; null means the listing is complete.
+     * This is the feed T9's sync reconciliation verb consumes.
+     */
+    listUpdatedSince(since: string, options?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<UpdatedSincePage>;
 }
 export declare function createRemoteSkillsClient(): RemoteSkillsClient | null;
+/**
+ * Write-free client resolution for read-only paths (e.g. `sync --dry-run`).
+ *
+ * createRemoteSkillsClient() resolves the stored credential through
+ * getAuthFilePath() and the stored origin through loadConfig() — both route
+ * through getDataDir(), which WRITES (mkdirs the app dir, merges legacy ~/.skills
+ * content, copies the legacy config). A dry run must resolve the same client a
+ * real run would without performing any of that: the credential and the origin
+ * are read from the same files at the same computed paths, and the MissingApiUrl
+ * failure mode is preserved (a key with no origin still fails loudly).
+ */
+export declare function createRemoteSkillsClientReadOnly(): RemoteSkillsClient | null;