dsh-home-hosted 0.2.2 → 0.3.2

package/lib/types/home-hosted/dsh-entry.d.ts

@@ -16,7 +16,70 @@ export interface DshFacts {
     profile: string | null;
     dshHome: string;
     launch: CliLaunch | null;
+    /**
+     * The stable launcher a local/clone entry must boot through, when one exists.
+     * Null keeps the older shape: the resolved program and its own argv.
+     */
+    launcherPath?: string | null;
 }
-/** Where the running harness's own CLI entry is, if we can tell. */
-export declare function resolveDshLaunch(): Promise<CliLaunch | null>;
+export interface DshLaunch extends CliLaunch {
+    /** The stable launcher written for this launch, or null for `dsh` on PATH. */
+    launcherPath: string | null;
+}
+export interface ResolveDshLaunchOptions {
+    /** The plugin state dir the launcher is written into; defaults to `$DSH_HOME/dsh-home-hosted`. */
+    stateDir?: string;
+    /** The harness home the resolver records as the launcher's search root. */
+    dshHome?: string;
+    /** Test seam: what this process was launched as; defaults to `process.argv[1]`. */
+    argv1?: string | null;
+    /** Test seam: locate a command on PATH. */
+    findOnPath?: (command: string) => Promise<string | null>;
+}
+/**
+ * A local clone's built entry, reconstructed from where a clone keeps its build.
+ *
+ * A clone installs dsh in its own tree, so `argv[1]` names a *build output*
+ * (`lib/bin.js` inside `node_modules`, and after a rebuild a different one): the
+ * install root is derived from it and every known build location is checked, so a
+ * rebuild does not require a new boot entry.
+ */
+export declare function cloneEntryFrom(argv1: string): string | null;
+/** The best dsh entry installed under a harness home, flat or pnpm. */
+export declare function findDshEntry(dshHome: string): string | null;
+/**
+ * Where the running harness's own CLI entry is.
+ *
+ * A local clone's build path is not stable enough to bake into a boot entry, so
+ * the clone case records the entry in a generated launcher and returns that
+ * launcher's path; the launcher re-finds dsh at boot. A plain `dsh` on PATH is
+ * already resolved to a stable entry and keeps its current shape.
+ */
+export declare function resolveDshLaunch(options?: ResolveDshLaunchOptions): Promise<DshLaunch | null>;
+/**
+ * Re-point an entry that boots a local build directly at the stable launcher.
+ *
+ * Only this shape qualifies: the entry runs the same script this process does,
+ * and that script is not already the launcher. An upgrade cannot repair the
+ * entry it created in an earlier release otherwise — the plugin never rewrites
+ * an existing entry's command.
+ */
+/**
+ * Whether an entry *could* need that repair, without resolving anything.
+ *
+ * Resolving a local dsh walks the harness home, so the write path asks this
+ * first: a global `dsh` on PATH, or an entry already on the launcher, is
+ * settled here and never triggers the walk.
+ */
+export declare function needsLauncherRepair(config: {
+    command?: string;
+    args?: string[];
+}): boolean;
+export declare function launcherRepair(config: {
+    command?: string;
+    args?: string[];
+}, launch: DshLaunch | null): {
+    command: string;
+    args: string[];
+} | null;
 export declare function buildDshEntry(facts: DshFacts): ServerEntry;

package/lib/types/home-hosted/launcher.d.ts

@@ -35,4 +35,52 @@ export declare function versionOfEntry(entry: string): string | null;
 export declare function candidatesUnder(root: string): string[];
 /** Highest satisfying candidate among explicit roots; exported for tests. */
 export declare function findCandidate(roots: string[], minVersion: string): string | null;
+export interface DshLauncherOptions {
+    stateDir: string;
+    dshHome: string;
+    /** Where the dsh entry is right now; recorded as the fast path. */
+    resolvedEntry: string | null;
+    /** The extension the launcher must match: a `.cjs` entry gets a `.cjs` launcher. */
+    entryExtension?: string | null;
+    /**
+     * Install roots that are neither the harness home nor PATH — a clone, or a
+     * project whose own `node_modules` carries dsh. Recorded and searched, so a
+     * moved build is re-found on the next boot.
+     */
+    searchRoots?: string[] | null;
+}
+export interface DshLauncherWrite {
+    path: string;
+    changed: boolean;
+}
+interface DshLauncherRecord {
+    entry: string | null;
+    /** Where that entry's install sat, kept across rewrites while it stays valid. */
+    roots: string[];
+    writtenAt: number;
+}
+/** The recorded entry a boot entry baked in, for the launcher's fast path. */
+export declare function dshLauncherRecordPath(stateDir: string): string;
+/** `bin/dsh.mjs`, or `bin/dsh.cjs` when the recorded entry is CommonJS. */
+export declare function dshLauncherPath(stateDir: string, entryExtension?: string | null): string;
+export declare function readDshLauncherRecord(stateDir: string): DshLauncherRecord | null;
+/**
+ * The dsh launcher's source.
+ *
+ * Like the home-hosted launcher, this exists because a clone's build output path
+ * (or a versioned pnpm path) moves on the next install/rebuild: the boot entry
+ * points at this stable script and the script re-finds dsh at every boot. A
+ * `.cjs` entry gets a CommonJS launcher, so node loads it as one.
+ */
+export declare function buildDshLauncherSource(options: DshLauncherOptions): string;
+/** Write the launcher and record what `resolveDshLaunch` found. */
+export declare function writeDshLauncher(options: DshLauncherOptions): DshLauncherWrite;
+/** A dsh entry under one root: a flat install, or either pnpm store layout. */
+export declare function dshCandidatesUnder(root: string): string[];
+/**
+ * The install root a dsh entry belongs to: the directory whose `node_modules`
+ * carries it — a clone root, or the project that installed dsh. That root is
+ * what a rebuilt or upgraded install keeps.
+ */
+export declare function dshSearchRoot(entry: string | null | undefined): string | null;
 export {};

package/lib/types/home-hosted/panel.d.ts

@@ -40,5 +40,17 @@ export declare class PanelClient {
         stopped?: number[];
     }>;
 }
+/**
+ * What a token probe measured: `ok` — the panel accepted it; `refused` — the
+ * panel answered and rejected it; `unreachable` — the panel was not there to
+ * ask, which is not the same as a refusal.
+ */
+export type TokenProbe = 'ok' | 'refused' | 'unreachable';
+/**
+ * Prove a token with a non-mutating `listServers()`, and say whether the panel
+ * refused it or merely was not answering. A timeout or connection error must
+ * never be reported as a stale token.
+ */
+export declare function probeToken(baseUrl: string, token: string, timeoutMs?: number): Promise<TokenProbe>;
 /** Prove a token works, without needing any write permission. */
 export declare function verifyToken(baseUrl: string, token: string, timeoutMs?: number): Promise<boolean>;

package/lib/types/home-hosted/resolve.d.ts

@@ -1,7 +1,7 @@
 import type { CliStatus } from '../shared/contracts.js';
 import type { CliLaunch } from './launch.js';
 /** The range the plugin ships and is tested against. */
-export declare const EXPECTED_RANGE = "^0.6.4";
+export declare const EXPECTED_RANGE = "^0.6.6";
 /** Oldest release whose API and config schema this plugin relies on. */
 export declare const MIN_SUPPORTED_VERSION = "0.4.1";
 /** Oldest release whose config schema accepts `onPortConflict: kill`. */

package/lib/types/home-hosted/token.d.ts

@@ -11,6 +11,15 @@ export interface EnsureTokenResult {
     enrolled: boolean;
     detail: string;
 }
+export interface ReclaimTokenOptions {
+    home: string;
+    stateDir: string;
+    exec: CliExecutor;
+}
+export interface ReclaimTokenResult {
+    token: string | null;
+    detail: string;
+}
 export declare function storedTokenPath(stateDir: string): string;
 export declare function readStoredToken(stateDir: string): string | null;
 export declare function storeToken(stateDir: string, token: string): void;
@@ -18,3 +27,14 @@ export declare function generateToken(): string;
 /** Whether home-hosted already holds an API token (only its hash is on disk). */
 export declare function apiTokenEnrolled(home: string): boolean;
 export declare function ensureToken(options: EnsureTokenOptions): Promise<EnsureTokenResult>;
+/**
+ * Replace the panel's API token with a fresh one.
+ *
+ * home-hosted keeps only the token's hash, so a token this plugin does not hold
+ * cannot be recovered: a fresh token is minted, enrolled through the same
+ * `HHOSTED_TOKEN` path `ensureToken` uses — one write, since `set-token` replaces
+ * whatever hash is there — and only then is the plaintext stored 0600. The
+ * attempted write carries no risk to the stored token: a failure replaced
+ * nothing, so the previous plaintext is kept.
+ */
+export declare function reclaimToken(options: ReclaimTokenOptions): Promise<ReclaimTokenResult>;

package/lib/types/service.d.ts

@@ -9,6 +9,7 @@
 import { Service, type Context } from '@deepseek-ai/cordis';
 import type { BootMechanism, BootStatus, HomeHostedStatus, ManagedEntryStatus, PanelControlResult, PanelStatus, RpcEndpoint, UiAction, UiResult } from './shared/contracts.js';
 import type { BootSpec } from './boot/types.js';
+import type { DshLaunch } from './home-hosted/dsh-entry.js';
 import type { SettingsStore } from './settings.js';
 import type { RunResult } from './util/exec.js';
 /** What a boot install/uninstall answers with; mirrors the boot module's shape. */
@@ -42,13 +43,23 @@ export interface HomeHostedServiceOptions {
     execCli?: (args: string[], env: Record<string, string | undefined>) => Promise<RunResult>;
     /** Test seam: supply the boot ladder instead of probing the real OS. */
     createLadder?: () => BootLadderLike;
+    /** Test seam: resolve the running harness instead of reading this process. */
+    resolveDsh?: (options: {
+        dshHome: string;
+        stateDir: string;
+    }) => Promise<DshLaunch | null>;
 }
 export declare class HomeHostedService extends Service {
     private readonly options;
     private clientCache;
+    /** The last token this service proved against a panel, so a poll does not re-probe it. */
+    private tokenProof;
     private tokenDetail;
+    /** When a missing managed entry was last put back, so a poll cannot become a write loop. */
+    private entryRecoveryAt;
     private readonly snapshotsFile;
     constructor(ctx: Context, options: HomeHostedServiceOptions);
+    private resolveDsh;
     private runtime;
     /** The entry id this very process was started as, when the panel supervises us. */
     selfEntryId(): string | null;
@@ -69,13 +80,36 @@ export declare class HomeHostedService extends Service {
     private configuredPort;
     /** Write the chosen panel port into the state the panel boots from. */
     private applyPanelPort;
+    /** Whether this exact token was already proved against this exact panel. */
+    private tokenProven;
+    private proveToken;
     panelStatus(): Promise<PanelStatus>;
+    /**
+     * Replace the panel's API token with a fresh one and prove it.
+     *
+     * home-hosted keeps only a hash, so a token this plugin does not hold cannot
+     * be recovered: a new token replaces the old hash in one CLI write, and it is
+     * proved against the answering panel before being reported.
+     *
+     * The panel is not required to be *answering*: a missing or refused token is a
+     * common reason it cannot be reached at all, and refusing the repair for that
+     * reason would leave no way out from the page. Only a panel that was never
+     * started is refused — there is nothing to enrol a token against yet.
+     */
+    reclaimPanelToken(): Promise<HomeHostedStatus>;
     private tryClient;
     private requireClient;
     private snapshots;
     private saveSnapshots;
     private liveEntries;
     private createEntry;
+    /**
+     * An entry written before the launcher existed still runs a clone's build
+     * output directly. Point it at the stable launcher, or the fix would only
+     * ever apply to freshly created entries — the plugin never rewrites an
+     * existing entry's command.
+     */
+    private dshCommandRepair;
     private writeOwned;
     private panelRunning;
     /**
@@ -133,6 +167,18 @@ export declare class HomeHostedService extends Service {
      * an explicit click or an approved tool call, not as a side effect of startup.
      */
     reconcile(): Promise<void>;
+    /**
+     * Put back a managed entry that no longer exists, while its intent still wants
+     * autostart. A paused intent is a deliberate stop and is left alone.
+     *
+     * Called from startup `reconcile()` as well as the status read, because a person
+     * who deletes the entry from the panel is looking at the page right then — not
+     * at the next plugin start. A failed attempt is not repeated for a while, so a
+     * config that cannot be written does not turn every poll into a write.
+     */
+    private ensureManagedEntry;
+    /** Re-assert the boot entry when the OS still has it but it stopped working. */
+    private repairBootEntry;
     status(): Promise<HomeHostedStatus>;
     call(endpoint: RpcEndpoint, payload: unknown): Promise<unknown>;
 }

package/lib/types/shared/contracts.d.ts

@@ -21,7 +21,7 @@ export type Envelope<T> = {
     error: RpcError;
 };
 /** Endpoints the browser and the agent tools both speak. */
-export type RpcEndpoint = 'status' | 'servers.list' | 'servers.get' | 'servers.create' | 'servers.update' | 'servers.delete' | 'servers.start' | 'servers.stop' | 'servers.restart' | 'servers.freePort' | 'entries.apply' | 'entries.remove' | 'entries.restore' | 'boot.install' | 'boot.uninstall' | 'boot.verify' | 'panel.start' | 'panel.takeover' | 'cli.installGlobal' | 'ui.manage' | 'settings.update';
+export type RpcEndpoint = 'status' | 'servers.list' | 'servers.get' | 'servers.create' | 'servers.update' | 'servers.delete' | 'servers.start' | 'servers.stop' | 'servers.restart' | 'servers.freePort' | 'entries.apply' | 'entries.remove' | 'entries.restore' | 'boot.install' | 'boot.uninstall' | 'boot.verify' | 'panel.start' | 'panel.takeover' | 'panel.reclaimToken' | 'cli.installGlobal' | 'ui.manage' | 'settings.update';
 /** A settings write sends only the changed subtree; the host merges group by group. */
 export interface SettingsPatch {
     autostart?: Partial<PluginSettings['autostart']>;
@@ -29,6 +29,7 @@ export interface SettingsPatch {
     entries?: PluginSettings['entries'];
     panel?: Partial<PluginSettings['panel']>;
     authNotice?: boolean;
+    reclaimToken?: boolean;
     uiStyle?: UiStyle;
     agentTools?: Partial<PluginSettings['agentTools']>;
     cli?: Partial<PluginSettings['cli']>;
@@ -87,6 +88,11 @@ export interface EndpointPayloads {
     'panel.takeover': {
         force?: boolean;
     };
+    /**
+     * Mint a fresh panel API token and enrol it, replacing one the panel refuses.
+     * Clearing first is what makes it work when home-hosted already holds a hash.
+     */
+    'panel.reclaimToken': Record<string, never>;
     /** Install the pinned range as a global CLI, so the `global` preference can use it. */
     'cli.installGlobal': Record<string, never>;
     /** Drive the panel's own UI: status, update, revert, or switch to a local build. */
@@ -143,7 +149,7 @@ export interface EntryIntent {
     stopKillPortHolders: boolean;
 }
 /** Keys an intent owns: a patch touches these and nothing else. */
-export declare const OWNED_ENTRY_KEYS: readonly ["autostart", "onPortConflict", "stop"];
+export declare const OWNED_ENTRY_KEYS: readonly ["autostart", "onPortConflict", "persistent", "stop"];
 export interface ServerEntryView {
     id: string;
     status: string;
@@ -161,7 +167,12 @@ export interface ManagedEntryStatus {
     live: ServerEntryView | null;
     snapshot: ServerEntry | null;
 }
-export type TokenState = 'enrolled' | 'present' | 'absent' | 'unknown';
+/**
+ * `enrolled` — the plugin holds a token; `present` — home-hosted has one this
+ * plugin does not hold; `absent` — none exists yet; `stale` — the plugin holds
+ * one the panel just refused; `unknown` — the panel was not reachable to ask.
+ */
+export type TokenState = 'enrolled' | 'present' | 'absent' | 'stale' | 'unknown';
 export interface PanelStatus {
     /** `$HHOSTED_HOME` this plugin resolved, whether or not the panel answers. */
     home: string;
@@ -174,6 +185,8 @@ export interface PanelStatus {
     /** How writes are authenticated right now. */
     writeVia: 'api' | 'file' | 'none';
     token: TokenState;
+    /** True when the panel was asked and accepted the token, so `token` is measured, not assumed. */
+    tokenVerified?: boolean;
     detail: string;
 }
 /** Which home-hosted CLI the plugin drives, and where it came from. */
@@ -280,6 +293,12 @@ export interface PluginSettings {
     };
     /** Point dsh web's sign-in page at the panel log that holds the tokenised URL. */
     authNotice: boolean;
+    /**
+     * When the panel refuses the plugin's API token, re-enrol one on the spot
+     * instead of failing the call. On by default: a token that went stale (someone
+     * cleared it, or minted their own) should not keep an agent tool from working.
+     */
+    reclaimToken: boolean;
     /** `detailed` shows cards and open disclosures; `compact` folds both away. */
     uiStyle: UiStyle;
     cli: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-home-hosted",
-  "version": "0.2.2",
+  "version": "0.3.2",
   "description": "DeepSeek Harness (dsh) plugin: start your dsh web server automatically at boot, and manage home-hosted's panel and servers from inside dsh.",
   "type": "module",
   "license": "MIT",
@@ -117,6 +117,6 @@
     "vitest": "^2.1.8"
   },
   "dependencies": {
-    "home-hosted": "^0.6.4"
+    "home-hosted": "^0.6.6"
   }
 }