dsh-plugin-standalone-session 0.0.0-stage → 0.1.0

package/lib/types/client/dsh.d.ts

@@ -0,0 +1,167 @@
+/**
+ * The narrow, structurally typed DSH browser surface this plugin consumes.
+ *
+ * DSH's own client packages are provided by the running host's module graph,
+ * not by npm at this plugin's version. Declaring only the faces used here keeps
+ * the plugin buildable without importing stale published type packages.
+ */
+import type { ComponentType } from 'react';
+/** Observable snapshot source shared by the workspace and session controllers. */
+export interface ObservableSnapshot<T> {
+    getSnapshot(): T;
+    subscribe(listener: () => void): () => void;
+}
+/** One Session catalog row, as consumed by the sidebar and this plugin's panel. */
+export interface SessionRow {
+    readonly id: string;
+    readonly title?: string;
+    readonly displayTitle: string;
+    readonly cwd?: string;
+    readonly parentId?: string;
+    readonly origin?: 'subagent';
+    readonly running: boolean;
+    readonly blank: boolean;
+    readonly updatedAt: number;
+}
+/** Complete Session catalog snapshot. */
+export interface SessionListState {
+    readonly ids: readonly string[];
+    readonly byId: Readonly<Record<string, SessionRow>>;
+    readonly phase?: string;
+}
+/** One workspace row from the Workspace follow stream. */
+export interface WorkspaceRow {
+    readonly workspaceId: string;
+    readonly path: string;
+    readonly title: string;
+    readonly sessionIds: readonly string[];
+}
+/** Complete workspace snapshot. */
+export interface WorkspaceSnapshot {
+    readonly items: readonly WorkspaceRow[];
+    readonly archivedSessionIds: readonly string[];
+    readonly pinnedSessionIds?: readonly string[];
+    readonly phase?: string;
+}
+/** Remote failure/result envelope returned by Session mutations. */
+export type RemoteResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    };
+};
+/** One retained Client Session generation. */
+export interface SessionReference {
+    readonly binding: {
+        readonly session: {
+            rename(title: string): Promise<RemoteResult<{
+                readonly title: string;
+                readonly seq: number;
+            }>>;
+        };
+    };
+    release(): void;
+}
+/** Browser Session service (`ctx.sessions`). */
+export interface SessionService {
+    readonly list: ObservableSnapshot<SessionListState>;
+    create(options?: {
+        workspaceId?: string;
+        cwd?: string;
+        sessionId?: string;
+        agentPreset?: string;
+    }): Promise<string>;
+    using<T>(target: string, options: {
+        source: string;
+        signal?: AbortSignal;
+    }, operation: (reference: SessionReference) => T | Promise<T>): Promise<T>;
+}
+/** Browser Workspace service (`ctx.workspaces`). */
+export interface WorkspaceService {
+    readonly list: ObservableSnapshot<WorkspaceSnapshot>;
+    create(input: {
+        path: string;
+    }): Promise<WorkspaceRow>;
+    delete(workspaceId: string): Promise<void>;
+    archiveSession(sessionId: string, options?: {
+        readonly stopActivity?: boolean;
+    }): Promise<void>;
+    unarchiveSession(sessionId: string): Promise<void>;
+}
+/** Cross-controller navigation (`ctx.uiWorkspace`). */
+export interface UiWorkspaceService {
+    openSession(target: string): void;
+    startSession(workspaceId?: string): void;
+}
+/** Localized translate function. */
+export interface Translate {
+    (key: string, values?: Readonly<Record<string, string | number>>): string;
+}
+/** Browser locale registry (`ctx.locale`). */
+export interface LocaleService {
+    register(namespace: string, dictionaries: Readonly<Record<string, Readonly<Record<string, string>>>>): () => void;
+    bind(namespace: string): Translate;
+}
+/** One client command contribution accepted by `ctx.commandUi`. */
+export interface CommandContribution {
+    readonly name: string;
+    label?(): string;
+    description?(): string;
+    readonly icon?: ComponentType<{
+        size?: number;
+    }>;
+    available(session: unknown): boolean;
+    readonly ui: {
+        readonly kind: 'action';
+        run(session: unknown): void;
+    } | {
+        readonly kind: 'popupSelect';
+        options(session: unknown, signal: AbortSignal): Promise<readonly unknown[]>;
+        onSelect(option: unknown, session: unknown): void | Promise<void>;
+    };
+}
+/** Browser command registry (`ctx.commandUi`). */
+export interface CommandUiService {
+    register(contribution: CommandContribution): () => void;
+}
+/** Layout panel selection (`ctx.layout`). */
+export interface LayoutService {
+    selectPanel(panelId: string | null): void;
+}
+/** One slot ledger entry (the registrant object behind a slot render). */
+export interface SlotEntry {
+    readonly options?: {
+        readonly priority?: number;
+        readonly [key: string]: unknown;
+    };
+    component: ComponentType<any>;
+    readonly [key: string]: unknown;
+}
+/** Slot registry (`ctx.slots`). */
+export interface SlotService {
+    inject(name: string, factory: () => unknown): () => void;
+    register(entry: Readonly<Record<string, unknown>>, component: ComponentType<any>): () => void;
+    entries(name: string): readonly SlotEntry[];
+    subscribe?(name: string, listener: () => void): () => void;
+}
+/** Cordis effect helper and service lookup. */
+export interface ClientContext {
+    readonly slots: SlotService;
+    readonly locale: LocaleService;
+    readonly sessions: SessionService;
+    readonly workspaces: WorkspaceService;
+    readonly uiWorkspace: UiWorkspaceService;
+    readonly commandUi: CommandUiService;
+    readonly layout: LayoutService;
+    readonly remote?: {
+        readonly $host?: {
+            readonly home?: string;
+        };
+    };
+    effect(execute: () => (() => void) | void, label?: string): unknown;
+    get(name: string): unknown;
+}

package/lib/types/client/format.d.ts

@@ -0,0 +1,10 @@
+import type { Translate } from './dsh.js';
+/**
+ * Localize `relativeTime` output. The shared helper stays locale-neutral for
+ * non-UI callers; this adapter maps its compact m/h/d units to copy.
+ * @param t - localized copy.
+ * @param timestamp - last update time.
+ * @param now - injectable clock for tests.
+ * @returns localized relative time, or an empty string for an invalid stamp.
+ */
+export declare function relativeTimeLabel(t: Translate, timestamp: number, now?: number): string;

package/lib/types/client/hooks.d.ts

@@ -0,0 +1,31 @@
+import type { ClientContext, ObservableSnapshot, SessionListState, SessionRow, WorkspaceSnapshot } from './dsh.js';
+/** Subscribe one component to an observable snapshot. */
+export declare function useSnapshot<T>(source: ObservableSnapshot<T>): T;
+/** The complete Session catalog. */
+export declare function useSessionList(ctx: ClientContext): SessionListState;
+/** The complete Workspace snapshot (used for the archive set). */
+export declare function useWorkspaceSnapshot(ctx: ClientContext): WorkspaceSnapshot;
+/**
+ * One session's durable cwd. A missing row or id yields undefined, which is
+ * also the "not standalone" answer.
+ * @param ctx - client root context.
+ * @param sessionId - rendered session, if any.
+ * @returns the session cwd, or undefined.
+ */
+export declare function useSessionCwd(ctx: ClientContext, sessionId: string | undefined): string | undefined;
+/**
+ * Standalone rows in display order: blank sessions first, then newest activity.
+ * Archived rows are excluded; the native archived view remains the restore
+ * surface.
+ * @param sessions - catalog snapshot.
+ * @param archivedSessionIds - Host archive set.
+ * @returns the standalone rows.
+ */
+export declare function standaloneRows(sessions: SessionListState, archivedSessionIds: readonly string[]): SessionRow[];
+/**
+ * Count standalone rows without constructing the full display list.
+ * @param sessions - catalog snapshot.
+ * @param archivedSessionIds - Host archive set.
+ * @returns the number of live standalone sessions.
+ */
+export declare function countStandalone(sessions: SessionListState, archivedSessionIds: readonly string[]): number;

package/lib/types/client/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Browser half of `dsh-plugin-standalone-session`: a dedicated sidebar/panel
+ * area, a direct creation action, a command contribution, native-row badges
+ * and the composer adapter that makes a workspace-free session usable.
+ *
+ * Composition is additive: every registration lands in an existing DSH list
+ * seat or keyed panel. The native New Session action, workspace browser,
+ * picker, session menus and chat surface are not replaced.
+ */
+import type { ClientContext } from './dsh.js';
+export { NEW_PANEL_ID, PANEL_ID } from './panels.js';
+/** Services this client plugin requires. */
+export declare const inject: string[];
+/**
+ * Register the browser half.
+ * @param ctx - Cordis client root context.
+ */
+export declare function apply(ctx: ClientContext): void;

package/lib/types/client/launcher.d.ts

@@ -0,0 +1,39 @@
+import type { SessionListState } from './dsh.js';
+/** How long a row click remains a valid launcher gesture. */
+export declare const LAUNCHER_ARM_WINDOW_MS = 3000;
+/** Record a real click on the launcher row. */
+export declare function armStandaloneLauncher(now?: number): void;
+/** Whether a recent real click armed the launcher, without consuming it. */
+export declare function isStandaloneLauncherArmed(now?: number): boolean;
+/** Consume the arm flag. */
+export declare function clearStandaloneLauncherArm(): void;
+/** Result of one launcher invocation. */
+export interface StandaloneLaunchResult {
+    readonly sessionId: string;
+    readonly reused: boolean;
+}
+/** Injected facts and effects for {@link StandaloneLaunchCoordinator}. */
+export interface StandaloneLaunchDeps {
+    readonly sessions: () => SessionListState;
+    readonly archivedSessionIds: () => readonly string[];
+    readonly create: () => Promise<string>;
+}
+/**
+ * Serialize launcher creates and reuse the last blank session it created.
+ * The class never opens a session; the caller owns navigation and its own
+ * mounted guard.
+ */
+export declare class StandaloneLaunchCoordinator {
+    private readonly deps;
+    private lastLauncherSessionId;
+    private inFlight;
+    constructor(deps: StandaloneLaunchDeps);
+    /**
+     * Launch one conversation: reuse the last blank bridged session when it is
+     * still live, otherwise create a new one.
+     * @returns the session to open and whether it was reused.
+     */
+    launch(): Promise<StandaloneLaunchResult>;
+    private run;
+    private reusableSession;
+}

package/lib/types/client/locales.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Browser dictionaries. `zh` is the key-set source of truth; the checked type
+ * keeps `en` complete, and both shipped languages are registered together.
+ */
+export declare const NS = "standaloneSession";
+export type StandaloneKey = 'panel.label' | 'panel.title' | 'panel.description' | 'panel.new' | 'panel.empty' | 'panel.emptyHint' | 'panel.badge' | 'panel.open' | 'panel.rename' | 'panel.delete' | 'panel.untitled' | 'panel.blank' | 'panel.running' | 'panel.cwd' | 'panel.count' | 'panel.deleteTitle' | 'panel.deleteBody' | 'panel.deleteConfirm' | 'panel.deleteKeepDir' | 'panel.cancel' | 'panel.renameTitle' | 'panel.renameLabel' | 'panel.more' | 'panel.save' | 'panel.titleRequired' | 'panel.actionFailed' | 'panel.retry' | 'panel.archivedHint' | 'panel.loading' | 'entry.label' | 'launcher.creating' | 'launcher.failedTitle' | 'launcher.retry' | 'launcher.manage' | 'launcher.hint' | 'command.label' | 'command.description' | 'command.manageLabel' | 'command.manageDescription' | 'footer.manage' | 'footer.manageCount' | 'footer.manageTooltip' | 'time.now' | 'time.minutes' | 'time.hours' | 'time.days' | 'toast.manageFailed' | 'hero.badge' | 'hero.hint' | 'row.mark' | 'row.hover' | 'composer.placeholder' | 'toast.created' | 'toast.createFailed' | 'toast.deleteFailed' | 'toast.deleted' | 'toast.renamed' | 'toast.renameFailed' | 'error.noHome' | 'error.noSession';
+export type StandaloneDict = Readonly<Record<StandaloneKey, string>>;
+export declare const zh: StandaloneDict;
+export declare const en: StandaloneDict;

package/lib/types/client/notice.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A tiny process-local notice store backing one `shell.overlay` toast. It is
+ * deliberately session-free: creation errors can happen on the New Session
+ * page, where no session exists to host a native notice.
+ */
+export type NoticeKind = 'info' | 'error';
+export interface Notice {
+    readonly id: number;
+    readonly kind: NoticeKind;
+    readonly text: string;
+}
+/** Read the current notice (stable reference between changes). */
+export declare function getNoticeSnapshot(): Notice | null;
+/** Subscribe to notice changes. */
+export declare function subscribeNotice(listener: () => void): () => void;
+/**
+ * Show or replace the toast.
+ * @param kind - success/informational or failure styling.
+ * @param text - already-localized copy.
+ */
+export declare function showNotice(kind: NoticeKind, text: string): void;
+/** Dismiss the toast immediately. */
+export declare function dismissNotice(): void;

package/lib/types/client/panels.d.ts

@@ -0,0 +1,3 @@
+/** Stable main-panel identities shared by the launcher, manager and commands. */
+export declare const PANEL_ID = "standalone-sessions";
+export declare const NEW_PANEL_ID = "standalone-sessions-new";

package/lib/types/client/styles.d.ts

@@ -0,0 +1,10 @@
+/**
+ * One namespaced stylesheet. DSH theme variables carry the palette, so the
+ * plugin follows light/dark themes without owning color tokens.
+ */
+export declare const CSS = "\n.ss-panel {\n  box-sizing: border-box;\n  height: 100%;\n  min-height: 0;\n  overflow: auto;\n  padding: 32px clamp(20px, 5vw, 56px) 56px;\n  color: var(--dsw-alias-label-primary, #1f2328);\n  background: var(--dsw-specific-main-fill, transparent);\n}\n.ss-shell {\n  width: 100%;\n  max-width: 880px;\n  margin: 0 auto;\n}\n.ss-header {\n  display: flex;\n  align-items: flex-start;\n  gap: 16px;\n  justify-content: space-between;\n  flex-wrap: wrap;\n  margin-bottom: 8px;\n}\n.ss-titleRow {\n  display: flex;\n  align-items: center;\n  gap: 10px;\n  min-width: 0;\n}\n.ss-title {\n  font-size: 24px;\n  line-height: 32px;\n  font-weight: 600;\n  margin: 0;\n}\n.ss-description {\n  color: var(--dsw-alias-label-secondary, #59636e);\n  font-size: 13px;\n  line-height: 20px;\n  margin: 6px 0 0;\n  max-width: 560px;\n}\n.ss-count {\n  color: var(--dsw-alias-label-tertiary, #818b98);\n  font-size: 12px;\n  line-height: 20px;\n  margin-top: 6px;\n}\n.ss-countInline {\n  margin-top: 0;\n  align-self: center;\n}\n.ss-button {\n  font: inherit;\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  gap: 6px;\n  box-sizing: border-box;\n  min-height: 32px;\n  padding: 5px 12px;\n  border-radius: var(--dsw-radius-md, 10px);\n  border: 0.5px solid transparent;\n  cursor: pointer;\n  color: var(--dsw-alias-label-primary, #1f2328);\n  background: var(--dsw-alias-button-elevated-fill, #f3f4f6);\n  transition: background 120ms ease, border-color 120ms ease;\n}\n.ss-button:hover:not(:disabled) {\n  background: var(--dsw-alias-interactive-bg-hover, #e9ebee);\n}\n.ss-button:focus-visible {\n  outline: var(--dsw-focus-ring-width, 2px) solid\n    var(--dsw-focus-ring-color, var(--dsw-alias-state-business-primary, #3b82f6));\n  outline-offset: 1px;\n}\n.ss-button:disabled {\n  cursor: default;\n  opacity: 0.55;\n}\n.ss-buttonPrimary {\n  color: #fff;\n  background: var(--dsw-alias-state-business-primary, #2563eb);\n  border-color: var(--dsw-alias-state-business-primary, #2563eb);\n}\n.ss-buttonPrimary:hover:not(:disabled) {\n  background: var(--dsw-alias-state-business-primary, #2563eb);\n  filter: brightness(1.05);\n}\n.ss-buttonQuiet {\n  background: transparent;\n  border-color: var(--dsw-alias-border-l2, rgba(128, 128, 128, 0.22));\n}\n.ss-buttonDanger {\n  color: var(--dsw-alias-state-error-primary, #d1242f);\n  background: transparent;\n  border-color: var(--dsw-alias-border-l2, rgba(128, 128, 128, 0.22));\n}\n.ss-badge {\n  display: inline-flex;\n  align-items: center;\n  gap: 4px;\n  flex: none;\n  border-radius: 999px;\n  padding: 1px 8px 2px;\n  font-size: 11px;\n  line-height: 16px;\n  font-weight: 600;\n  letter-spacing: 0.01em;\n  color: var(--dsw-alias-label-primary-bluish, #1f4f8f);\n  background: var(--dsw-alias-state-business-tertiary, rgba(59, 130, 246, 0.12));\n  border: 0.5px solid var(--dsw-alias-interactive-bg-hover, rgba(59, 130, 246, 0.18));\n}\n.ss-list {\n  display: flex;\n  flex-direction: column;\n  gap: 8px;\n  margin: 20px 0 0;\n  padding: 0;\n  list-style: none;\n}\n.ss-row {\n  position: relative;\n  display: flex;\n  align-items: center;\n  gap: 14px;\n  box-sizing: border-box;\n  padding: 12px 14px;\n  border-radius: var(--dsw-radius-lg, 14px);\n  border: 0.5px solid var(--dsw-alias-border-l2, rgba(128, 128, 128, 0.2));\n  background: var(--dsw-alias-bg-elevated, rgba(255, 255, 255, 0.02));\n  cursor: pointer;\n  transition: background 120ms ease, border-color 120ms ease;\n}\n.ss-row:hover,\n.ss-row:focus-within {\n  border-color: var(--dsw-alias-border-l4, rgba(128, 128, 128, 0.35));\n  background: var(--dsw-alias-interactive-bg-hover, #e9ebee);\n}\n.ss-row:focus-visible {\n  outline: var(--dsw-focus-ring-width, 2px) solid\n    var(--dsw-focus-ring-color, var(--dsw-alias-state-business-primary, #3b82f6));\n  outline-offset: 1px;\n}\n.ss-row[aria-disabled=\"true\"] {\n  cursor: default;\n  opacity: 0.7;\n}\n.ss-rowMain {\n  min-width: 0;\n  flex: 1;\n  display: flex;\n  flex-direction: column;\n  gap: 3px;\n}\n.ss-rowTitleRow {\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  min-width: 0;\n}\n.ss-rowTitle {\n  font-size: 14px;\n  line-height: 20px;\n  font-weight: 600;\n  min-width: 0;\n  overflow: hidden;\n  text-overflow: ellipsis;\n  white-space: nowrap;\n}\n.ss-rowMeta {\n  color: var(--dsw-alias-label-tertiary, #818b98);\n  font-size: 12px;\n  line-height: 18px;\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  min-width: 0;\n  flex-wrap: wrap;\n}\n.ss-dotSep {\n  opacity: 0.5;\n}\n.ss-rowActions {\n  position: relative;\n  display: flex;\n  align-items: center;\n  gap: 6px;\n  flex: none;\n}\n.ss-rowMenuButton {\n  width: 28px;\n  height: 28px;\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  padding: 0;\n  border: 0;\n  border-radius: var(--dsw-radius-md, 10px);\n  background: transparent;\n  color: var(--dsw-alias-label-tertiary, #818b98);\n  font: inherit;\n  font-size: 18px;\n  line-height: 1;\n  cursor: pointer;\n  opacity: 0;\n  transition: background 120ms ease, color 120ms ease, opacity 120ms ease;\n}\n.ss-row:hover .ss-rowMenuButton,\n.ss-row:focus-within .ss-rowMenuButton,\n.ss-rowMenuOpen .ss-rowMenuButton {\n  opacity: 1;\n}\n.ss-rowMenuButton:hover:not(:disabled) {\n  color: var(--dsw-alias-label-primary, #1f2328);\n  background: var(--dsw-alias-interactive-bg-hover, #e9ebee);\n}\n.ss-rowMenuButton:focus-visible {\n  opacity: 1;\n  outline: var(--dsw-focus-ring-width, 2px) solid\n    var(--dsw-focus-ring-color, var(--dsw-alias-state-business-primary, #3b82f6));\n  outline-offset: 1px;\n}\n.ss-rowMenuButton:disabled {\n  cursor: default;\n  opacity: 0.35;\n}\n.ss-rowMenu {\n  position: absolute;\n  top: calc(100% + 4px);\n  right: 0;\n  z-index: 20;\n  min-width: 136px;\n  padding: 4px;\n  display: flex;\n  flex-direction: column;\n  gap: 2px;\n  border: 0.5px solid var(--dsw-alias-border-l4, rgba(128, 128, 128, 0.35));\n  border-radius: var(--dsw-radius-md, 10px);\n  background: var(--dsw-alias-bg-elevated, #fff);\n  box-shadow: 0 10px 28px rgba(0, 0, 0, 0.16);\n}\n.ss-rowMenu button {\n  box-sizing: border-box;\n  width: 100%;\n  padding: 6px 9px;\n  border: 0;\n  border-radius: 6px;\n  background: transparent;\n  color: var(--dsw-alias-label-primary, #1f2328);\n  font: inherit;\n  font-size: 13px;\n  line-height: 20px;\n  text-align: left;\n  cursor: pointer;\n}\n.ss-rowMenu button:hover:not(:disabled),\n.ss-rowMenu button:focus-visible {\n  background: var(--dsw-alias-interactive-bg-hover, #e9ebee);\n  outline: none;\n}\n.ss-rowMenu button:disabled {\n  cursor: default;\n  opacity: 0.5;\n}\n.ss-rowMenuDanger {\n  color: var(--dsw-alias-state-error-primary, #d1242f) !important;\n}\n.ss-status {\n  display: inline-flex;\n  align-items: center;\n  gap: 5px;\n}\n.ss-statusDot {\n  width: 5px;\n  height: 5px;\n  border-radius: 50%;\n  background: currentColor;\n  opacity: 0.55;\n}\n.ss-stateRunning {\n  color: var(--dsw-alias-state-business-primary, #2563eb);\n  font-weight: 600;\n}\n.ss-empty {\n  margin-top: 28px;\n  padding: 44px 24px;\n  text-align: center;\n  border: 0.5px dashed var(--dsw-alias-border-l2, rgba(128, 128, 128, 0.3));\n  border-radius: var(--dsw-radius-lg, 14px);\n}\n.ss-emptyTitle {\n  font-size: 15px;\n  font-weight: 600;\n  line-height: 22px;\n  margin: 0 0 6px;\n}\n.ss-emptyHint {\n  color: var(--dsw-alias-label-secondary, #59636e);\n  font-size: 13px;\n  line-height: 20px;\n  margin: 0 auto;\n  max-width: 460px;\n}\n.ss-emptyAction {\n  margin-top: 18px;\n}\n.ss-panelHint {\n  margin: 18px 0 0;\n  color: var(--dsw-alias-label-tertiary, #818b98);\n  font-size: 12px;\n  line-height: 20px;\n}\n.ss-fieldLabel {\n  display: block;\n  margin: 12px 0 6px;\n  color: var(--dsw-alias-label-secondary, #59636e);\n  font-size: 12px;\n  line-height: 18px;\n}\n.ss-error {\n  margin-top: 16px;\n  padding: 8px 10px;\n  border-radius: var(--dsw-radius-sm, 8px);\n  color: var(--dsw-alias-state-error-primary, #d1242f);\n  background: var(--dsw-alias-state-error-tertiary, rgba(209, 36, 47, 0.08));\n  font-size: 12px;\n  line-height: 18px;\n}\n.ss-dialogBackdrop {\n  position: fixed;\n  inset: 0;\n  z-index: 80;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  background: rgba(0, 0, 0, 0.28);\n  padding: 24px;\n}\n.ss-dialog {\n  width: 100%;\n  max-width: 440px;\n  box-sizing: border-box;\n  border-radius: var(--dsw-radius-lg, 14px);\n  border: 0.5px solid var(--dsw-alias-border-l4, rgba(128, 128, 128, 0.35));\n  background: var(--dsw-alias-bg-elevated, #fff);\n  padding: 20px;\n  box-shadow: 0 18px 48px rgba(0, 0, 0, 0.22);\n}\n.ss-dialogTitle {\n  margin: 0 0 6px;\n  font-size: 16px;\n  line-height: 24px;\n  font-weight: 600;\n}\n.ss-dialogBody {\n  margin: 0 0 14px;\n  color: var(--dsw-alias-label-secondary, #59636e);\n  font-size: 13px;\n  line-height: 20px;\n}\n.ss-input {\n  box-sizing: border-box;\n  width: 100%;\n  height: 36px;\n  border-radius: var(--dsw-radius-sm, 8px);\n  border: 0.5px solid var(--dsw-alias-border-l4, rgba(128, 128, 128, 0.35));\n  background: transparent;\n  color: inherit;\n  font: inherit;\n  padding: 0 10px;\n}\n.ss-dialogFooter {\n  display: flex;\n  justify-content: flex-end;\n  gap: 8px;\n  margin-top: 18px;\n}\n.ss-footerAction {\n  box-sizing: border-box;\n  width: 100%;\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  min-height: 30px;\n  padding: 4px 8px;\n  border: 0;\n  border-radius: var(--dsw-radius-md, 10px);\n  background: transparent;\n  color: var(--dsw-alias-label-secondary, #59636e);\n  font: inherit;\n  cursor: pointer;\n  text-align: left;\n}\n.ss-footerAction:hover {\n  color: var(--dsw-alias-label-primary, #1f2328);\n  background: var(--dsw-alias-interactive-bg-hover, #e9ebee);\n}\n.ss-footerAction:disabled {\n  cursor: default;\n  opacity: 0.55;\n}\n.ss-footerLabel {\n  min-width: 0;\n  overflow: hidden;\n  text-overflow: ellipsis;\n  white-space: nowrap;\n  font-size: 13px;\n}\n.ss-footerRail {\n  width: 36px;\n  height: 36px;\n  justify-content: center;\n  padding: 0;\n}\n.ss-panelIcon {\n  position: relative;\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n}\n.ss-launcher {\n  box-sizing: border-box;\n  min-height: 100%;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  padding: 32px;\n  color: var(--dsw-alias-label-primary, #1f2328);\n}\n.ss-launcherCard {\n  box-sizing: border-box;\n  width: 100%;\n  max-width: 430px;\n  padding: 30px 28px;\n  text-align: center;\n  border: 0.5px solid var(--dsw-alias-border-l2, rgba(128, 128, 128, 0.22));\n  border-radius: var(--dsw-radius-lg, 14px);\n  background: var(--dsw-alias-bg-elevated, rgba(255, 255, 255, 0.02));\n}\n.ss-launcherSpinner {\n  width: 22px;\n  height: 22px;\n  margin: 0 auto 14px;\n  border-radius: 50%;\n  border: 2px solid var(--dsw-alias-border-l2, rgba(128, 128, 128, 0.25));\n  border-top-color: var(--dsw-alias-state-business-primary, #2563eb);\n  animation: ss-spin 900ms linear infinite;\n}\n@keyframes ss-spin {\n  to { transform: rotate(360deg); }\n}\n.ss-launcherTitle {\n  margin: 0;\n  font-size: 15px;\n  line-height: 22px;\n  font-weight: 600;\n}\n.ss-launcherHint {\n  margin: 6px 0 0;\n  color: var(--dsw-alias-label-secondary, #59636e);\n  font-size: 13px;\n  line-height: 20px;\n}\n.ss-launcherActions {\n  display: flex;\n  flex-wrap: wrap;\n  justify-content: center;\n  gap: 8px;\n  margin-top: 18px;\n}\n.ss-heroBadge {\n  margin-right: 4px;\n}\n.ss-rowMark {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  width: 14px;\n  height: 14px;\n  border-radius: 4px;\n  font-size: 10px;\n  line-height: 1;\n  font-weight: 700;\n  color: var(--dsw-alias-label-primary-bluish, #1f4f8f);\n  background: var(--dsw-alias-state-business-tertiary, rgba(59, 130, 246, 0.14));\n  flex: none;\n}\n.ss-rowHover {\n  display: flex;\n  align-items: center;\n  gap: 6px;\n  color: #cfd3d6;\n  font-size: 12px;\n  line-height: 16px;\n}\n.ss-toast {\n  position: fixed;\n  left: 50%;\n  bottom: 28px;\n  transform: translateX(-50%);\n  z-index: 90;\n  max-width: min(520px, calc(100vw - 40px));\n  box-sizing: border-box;\n  padding: 9px 14px;\n  border-radius: var(--dsw-radius-md, 10px);\n  border: 0.5px solid var(--dsw-alias-border-l4, rgba(128, 128, 128, 0.35));\n  background: var(--dsw-alias-bg-elevated, #fff);\n  color: var(--dsw-alias-label-primary, #1f2328);\n  box-shadow: 0 12px 32px rgba(0, 0, 0, 0.18);\n  font-size: 13px;\n  line-height: 19px;\n  pointer-events: auto;\n}\n.ss-toastError {\n  color: var(--dsw-alias-state-error-primary, #d1242f);\n}\n.ss-visuallyHidden {\n  position: absolute;\n  width: 1px;\n  height: 1px;\n  padding: 0;\n  margin: -1px;\n  overflow: hidden;\n  clip: rect(0, 0, 0, 0);\n  white-space: nowrap;\n  border: 0;\n}\n@media (hover: none) {\n  .ss-rowMenuButton { opacity: 1; }\n}\n@media (max-width: 640px) {\n  .ss-panel { padding: 20px 14px 40px; }\n  .ss-row { flex-wrap: wrap; }\n  .ss-rowActions { width: 100%; justify-content: flex-end; }\n}\n";
+/**
+ * Insert (or replace) the plugin's one style element.
+ * @returns a disposer that removes the element.
+ */
+export declare function insertStyles(): () => void;

package/lib/types/host/registry.d.ts

@@ -0,0 +1,124 @@
+import { type StandaloneEntry, type StandaloneRegistryData } from '../shared/standalone.js';
+/** Minimal logger surface; DSH's logger and tests both satisfy it. */
+export interface RegistryLogger {
+    info(message: string): void;
+    warn(message: string): void;
+}
+/** Default logger: console with the plugin's uniform prefix. */
+export declare function prefixedLogger(prefix?: string): RegistryLogger;
+/** Outcome of one session-directory cleanup. */
+export type CleanupOutcome = {
+    readonly kind: 'removed';
+} | {
+    readonly kind: 'retained';
+    readonly reason: string;
+} | {
+    readonly kind: 'failed';
+    readonly error: string;
+};
+/** Facts used by {@link cleanupSessionDirectory}; injectable for tests. */
+export interface DirectoryOps {
+    stat(path: string): Promise<{
+        isDirectory(): boolean;
+    }>;
+    rm(path: string, options: {
+        recursive: true;
+        force: true;
+    }): Promise<void>;
+}
+/**
+ * Whether one path is inside another (same path counts).
+ * @param parent - containing directory.
+ * @param child - candidate path.
+ * @returns true when `child` is at or below `parent` lexically.
+ */
+export declare function isPathInside(parent: string, child: string): boolean;
+/**
+ * Whether the record's cwd is structurally one of this plugin's session
+ * directories: an absolute path whose final segment is the session id and
+ * whose parent is the standalone marker directory. This remains true when a
+ * custom `DSH_HOME` puts the root somewhere other than this process's root.
+ * @param entry - registry record.
+ * @returns whether deletion may target that directory.
+ */
+export declare function isOwnedSessionDirectory(entry: StandaloneEntry): boolean;
+/**
+ * Remove one session directory according to its record. Never deletes a path
+ * that is not the record's own session directory.
+ * @param entry - registry record.
+ * @param ops - filesystem operations, injectable for tests.
+ * @param logger - diagnostic sink.
+ * @returns the cleanup outcome.
+ */
+export declare function cleanupSessionDirectory(entry: StandaloneEntry, ops?: DirectoryOps, logger?: RegistryLogger): Promise<CleanupOutcome>;
+/**
+ * Durable registry with serialized, atomic writes.
+ *
+ * Every mutation runs on one promise chain, so concurrent session
+ * announcements cannot lose each other's records. A failed write keeps the
+ * in-memory value and surfaces the error to the caller; the next write retries
+ * the complete document.
+ */
+export declare class DurableStandaloneRegistry {
+    readonly rootDir: string;
+    readonly filePath: string;
+    private data;
+    private queue;
+    private loadPromise;
+    private loaded;
+    private readonly logger;
+    private readonly ops;
+    /**
+     * @param rootDir - directory holding session directories and the registry file.
+     * @param logger - diagnostic sink.
+     * @param ops - directory operations, injectable for tests.
+     */
+    constructor(rootDir: string, logger?: RegistryLogger, ops?: DirectoryOps);
+    /** Load the registry once, recovering a corrupt file by moving it aside. */
+    load(): Promise<void>;
+    private loadOnce;
+    /** Current immutable snapshot. */
+    snapshot(): StandaloneRegistryData;
+    /** All records in stable id order. */
+    list(): StandaloneEntry[];
+    /** One record, if present. */
+    get(sessionId: string): StandaloneEntry | undefined;
+    /** Await every queued mutation. */
+    flush(): Promise<void>;
+    /**
+     * Announce one standalone session (idempotent).
+     * @param summary - Host session summary facts.
+     */
+    announce(summary: {
+        readonly sessionId: string;
+        readonly cwd?: string;
+        readonly blank?: boolean;
+    }): Promise<void>;
+    /**
+     * Mark one session as having carried a user-authored durable message.
+     * @param sessionId - session identity.
+     */
+    markActivity(sessionId: string): Promise<void>;
+    /**
+     * Mark archived sessions and clean the ones whose archive is visible.
+     * @param archivedSessionIds - the Host's complete archive set.
+     * @returns cleanup outcomes keyed by session.
+     */
+    reconcileArchived(archivedSessionIds: ReadonlySet<string>, stillArchived?: (sessionId: string) => boolean): Promise<ReadonlyMap<string, CleanupOutcome>>;
+    /**
+     * Remove old empty session directories that neither the registry nor the
+     * live session store references. These are the residue of a failed create or
+     * a crash between mkdir and the session announcement.
+     * @param liveSessionIds - identities the Host currently holds.
+     * @param minimumAgeMs - only directories older than this are eligible.
+     * @returns identities whose directory was removed.
+     */
+    sweepOrphanDirectories(liveSessionIds: ReadonlySet<string>, minimumAgeMs?: number): Promise<string[]>;
+    /**
+     * Apply one pure mutation and persist it when the reference changed.
+     * @param mutator - pure registry transform.
+     */
+    private mutate;
+    /** Atomically replace the registry file. */
+    private write;
+}

package/lib/types/index.d.ts

@@ -0,0 +1,37 @@
+import { type RegistryLogger } from './host/registry.js';
+/** Cordis function-plugin name. */
+export declare const name = "standalone-session";
+/** The tidy shape of the events this plugin listens to. */
+interface SessionAddedSummary {
+    readonly sessionId?: string;
+    readonly cwd?: string;
+    readonly blank?: boolean;
+}
+/** The narrow Host context surface this plugin uses. */
+export interface StandaloneHostContext {
+    on(event: 'api-session/added', listener: (summary: SessionAddedSummary) => void): unknown;
+    on(event: 'api-session/activity', listener: (sessionId: string) => void): unknown;
+    effect(execute: () => (() => void) | void, label?: string): unknown;
+    get(name: string): unknown;
+    root?: {
+        get?: (name: string) => unknown;
+    };
+    logger?: Partial<RegistryLogger>;
+}
+/**
+ * Resolve the standalone root from the OS home.
+ *
+ * The browser half only receives `$host.home`, so both halves must agree on
+ * this path. DSH's default home is `~/.dsh`; a custom `DSH_HOME` moves DSH's
+ * own profile data but not this plugin's dedicated directory. Keeping the two
+ * halves in agreement is more important than following a custom harness home.
+ * @param home - OS home, injectable for tests.
+ * @returns `<home>/.dsh/dsh-standalone-sessions`.
+ */
+export declare function resolveStandaloneRoot(home?: string): string;
+/**
+ * Register the host half.
+ * @param ctx - Cordis Host context.
+ */
+export declare function apply(ctx: StandaloneHostContext): void;
+export {};