@hasna/skills 0.1.63 → 0.1.66

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 (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
+ *      (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

@@ -87,6 +87,34 @@ export declare const SKILLS_STORAGE_FALLBACK_ENV: {
     readonly syncBatchSize: "SKILLS_SYNC_BATCH_SIZE";
     readonly dryRun: "SKILLS_SYNC_DRY_RUN";
 };
+/**
+ * Compatibility contract for the `./storage` subpath (`@hasna/skills/storage`).
+ *
+ * Consumers — including private SaaS embedders — compile against this subpath.
+ * `version` is the contract version: it MUST be bumped on every breaking
+ * removal or rename of a listed member. `values` are the runtime exports
+ * (functions, classes, constants) and `types` the type-only exports the
+ * subpath guarantees; `src/storage-boundary.test.ts` imports the subpath and
+ * fails if a listed member is no longer exported, so a removal cannot land
+ * silently.
+ *
+ * The retirement this contract exists to make unrepeatable: in 0.1.61 the
+ * storage-mode label functions, their mode type, and the storage-mode env
+ * variables were removed from both the main entrypoint and this subpath (see
+ * the CHANGELOG entry for 0.1.61, "the deployment 'mode' concept is gone").
+ * Nothing replaced them with a successor — the mode concept is gone and must
+ * not be reintroduced. The replacement for the old question ("which mode am I
+ * in?") is configuration-derived status: call
+ * `getSkillsNativeStorageStatus()` (aliases `getSkillsStorageStatus` /
+ * `getStorageStatus`) and read `remote.databaseConfigured` /
+ * `remote.s3Configured`. On-box SQLite and files are always present; Postgres
+ * and S3 are used when, and only when, their variables are set.
+ */
+export declare const storageCapabilities: {
+    readonly version: 1;
+    readonly values: readonly ["SKILLS_NATIVE_STORAGE_ENV", "SKILLS_NATIVE_STORAGE_FALLBACK_ENV", "SKILLS_STORAGE_ENV", "SKILLS_STORAGE_FALLBACK_ENV", "SKILLS_STORAGE_TABLES", "STORAGE_TABLES", "SkillsPostgresSyncStore", "SkillsS3ObjectStore", "buildSkillsS3ObjectUrl", "createSkillsPostgresSyncStore", "createSkillsS3ObjectStore", "createSkillsSnapshotSyncRecord", "exportSkillsLocalSnapshot", "getSkillsNativeStorageStatus", "getSkillsStorageDatabaseEnv", "getSkillsStorageDatabaseUrl", "getSkillsStorageStatus", "getStorageDatabaseEnv", "getStorageDatabaseUrl", "getStorageStatus", "importSkillsLocalSnapshot", "planSkillsS3SnapshotUpload", "resolveSkillsNativeStorageConfig", "resolveStorageConfig", "signSkillsAwsV4Request", "skillsPostgresSyncSchemaSql", "storageCapabilities", "uploadSkillsSnapshotFilesToS3"];
+    readonly types: readonly ["AwsCredentials", "SignSkillsAwsV4RequestOptions", "SkillsFetch", "SkillsLocalSnapshot", "SkillsNativeStorageConfig", "SkillsNativeStorageStatus", "SkillsPostgresQueryClient", "SkillsS3ObjectStoreOptions", "SkillsS3PutObjectOptions", "SkillsS3SnapshotPlanEntry", "SkillsS3StoredObject", "SkillsSnapshotFile", "SkillsStorageTable", "SkillsSyncRecord"];
+};
 export declare function resolveSkillsNativeStorageConfig(env?: Record<string, string | undefined>): SkillsNativeStorageConfig;
 export declare function resolveStorageConfig(env?: Record<string, string | undefined>): SkillsNativeStorageConfig;
 export declare function getSkillsStorageDatabaseEnv(env?: Record<string, string | undefined>): string;
@@ -94,7 +122,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.
  *
@@ -69,5 +98,19 @@ export interface WriteCorpusSkillInput {
  * skill — but removes nothing else, so a re-pull never destroys sibling files.
  */
 export declare function writeCorpusSkill(input: WriteCorpusSkillInput, options?: PortableSkillOptions): PortableSkillWriteResult;
+/**
+ * Atomically replace the corpus entry for a metadata-only pull (todos b4d956a3):
+ * stage SKILL.md and skill.json in a sibling directory, then rename into place — the
+ * existing entry is moved aside first and removed only after the staged tree is in
+ * position. A failure at any point leaves either the old entry or nothing — never a
+ * partial skill, mirroring installBundleAtomically on the bundle path.
+ *
+ * The manifest construction is identical to writeCorpusSkill; what differs is that no
+ * write ever lands in the live target before the swap. The direct-overwrite order of
+ * writeCorpusSkill (SKILL.md, then skill.json) can destroy the prior good copy when a
+ * mid-write failure (ENOSPC, EISDIR, crash) hits between the two writes, leaving a
+ * truncated or mismatched SKILL.md/skill.json pair that loadRegistry then serves.
+ */
+export declare function installCorpusSkillAtomically(input: WriteCorpusSkillInput, options?: PortableSkillOptions): PortableSkillWriteResult;
 export declare function validatePortableSkillDirectory(name: string, skillPath: string): SkillValidationResult;
 export declare function runPortableSkill(name: string, args: string[], options?: PortableSkillRunOptions): Promise<PortableSkillRunResult>;

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-types.d.ts

@@ -20,6 +20,15 @@ export interface SkillMeta {
     kind?: SkillKind;
     availability?: SkillAvailabilityMetadata;
     source?: SkillSource;
+    /**
+     * Execution is server-owned per the published-skill contract: the skill's
+     * package.json declares `skills.runtime: "hosted"` or `skills.source:
+     * "remote" | "private-hosted"` (see isHostedMetadataPackage in
+     * hosted-skill-set.ts). A server-owned skill is submitted to the configured
+     * Skills API and never falls back to local execution (see resolveRunRouting
+     * in run-routing.ts). Absent means local execution is the contract.
+     */
+    serverOwned?: boolean;
 }
 export interface SkillAvailabilityMetadata {
     status: "available" | "unavailable";

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[];