@ai-agent-forge/agent-forge 0.85.0

package/dist/profiles/resolved-agent-profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolved-agent-profile.js","sourceRoot":"","sources":["../../src/profiles/resolved-agent-profile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EAAE,gBAAgB,EAAE,MAAM,mDAAmD,CAAC;AAwErF;;;;;GAKG;AACH,MAAM,UAAU,2BAA2B,CAAC,KAI3C,EAA0B;IAC1B,MAAM,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC;IAC5B,MAAM,aAAa,GAAG,KAAK,CAAC,aAAa,CAAC;IAC1C,MAAM,OAAO,GACZ,aAAa,KAAK,SAAS;QAC1B,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE;QACrB,CAAC,CAAC,aAAa,CAAC,MAAM,KAAK,UAAU;YACpC,CAAC,CAAC;gBACA,OAAO,EAAE,UAAU;gBACnB,SAAS,EAAE,aAAa,CAAC,OAAO,CAAC,EAAE;gBACnC,cAAc,EAAE,aAAa,CAAC,OAAO,CAAC,OAAO;gBAC7C,cAAc,EAAE,aAAa,CAAC,UAAU,CAAC,gBAAgB,CAAC,cAAc;gBACxE,SAAS,EAAE,aAAa,CAAC,UAAU,CAAC,gBAAgB,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC;aAC7F;YACF,CAAC,CAAC,aAAa,CAAC,MAAM,KAAK,mBAAmB;gBAC7C,CAAC,CAAC;oBACA,OAAO,EAAE,mBAAmB;oBAC5B,SAAS,EAAE,aAAa,CAAC,SAAS;oBAClC,gBAAgB,EAAE,CAAC,GAAG,aAAa,CAAC,gBAAgB,CAAC;oBACrD,kBAAkB,EAAE,CAAC,GAAG,aAAa,CAAC,kBAAkB,CAAC;iBACzD;gBACF,CAAC,CAAC,aAAa,CAAC,MAAM,KAAK,WAAW;oBACrC,CAAC,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,CAAC,SAAS,EAAE;oBAC9D,CAAC,CAAC,EAAE,OAAO,EAAE,qBAAqB,EAAE,SAAS,EAAE,aAAa,CAAC,SAAS,EAAE,CAAC;IAC9E,MAAM,WAAW,GAAkC;QAClD,GAAG,SAAS,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,OAAO,EAA+B,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;QACtG,GAAG,CAAC,aAAa,EAAE,MAAM,KAAK,UAAU;YACvC,CAAC,CAAC,aAAa,CAAC,UAAU,CAAC,WAAW,CAAC,GAAG,CACxC,CAAC,UAAU,EAA+B,EAAE,CAAC,CAAC;gBAC7C,MAAM,EAAE,gBAAgB;gBACxB,IAAI,EAAE,UAAU,CAAC,IAAI;gBACrB,OAAO,EAAE,UAAU,CAAC,OAAO;gBAC3B,GAAG,CAAC,UAAU,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,OAAO,EAAE,CAAC;aAC5E,CAAC,CACF;YACF,CAAC,CAAC,EAAE,CAAC;KACN,CAAC;IACF,OAAO,gBAAgB,CAAC;QACvB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,QAAQ,EAAE,SAAS,CAAC,QAAQ;QAC5B,GAAG,CAAC,SAAS,CAAC,gBAAgB,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,SAAS,CAAC,gBAAgB,EAAE,CAAC;QACrG,aAAa,EAAE,OAAO;QACtB,SAAS,EAAE;YACV,QAAQ,EAAE,SAAS,CAAC,QAAQ;YAC5B,aAAa,EAAE,SAAS,CAAC,aAAa;YACtC,YAAY,EAAE,SAAS,CAAC,YAAY;YACpC,QAAQ,EAAE,SAAS,CAAC,QAAQ;SAC5B;QACD,WAAW;KACX,CAAC,CAAC;AAAA,CACH","sourcesContent":["/**\n * ResolvedAgentProfile (D-047 S4a, docs/plans/G4-resolved-agent-profile设计注记.md):\n * the immutable per-session aggregate view over the resolved suite profile.\n *\n * S4d first increment: the aggregate additionally carries a build-time\n * `diagnostics` snapshot projected from SuiteWorkspace.diagnostics and the\n * resolved plugin profile's ProfileResolutionV1.diagnostics; the existing five\n * diagnostic channels are untouched and remain the live sources.\n *\n * This is an aggregate VIEW, not a new generation mechanism: every field\n * references an existing authoritative source (字段-权威映射 in the design\n * note), resolution still happens at the existing single point\n * (createAgentSession's suite+pluginProfile assembly, once per session), and\n * the builder only re-projects those sources and deep-freezes the result. The\n * aggregate lives at the resolution layer (session creation result and host\n * references); `AgentSession` stays suite-unaware — it never enters\n * AgentSessionConfig, and the session's persisted identity authority remains\n * the suite custom entry.\n */\nimport { detachedSnapshot } from \"../core/extensions/capability-runtime-snapshot.ts\";\nimport type { PluginDiagnosticCodeV1 } from \"../plugins/ecosystem/types.ts\";\nimport type { ProfileIdentityV1 } from \"../profile/identity.ts\";\nimport type { ProfileLockVerificationV1 } from \"../profile/lock.ts\";\nimport type { BuiltinPluginProfileResolutionV1 } from \"../profile/plugin-profiles.ts\";\nimport type { SuiteWorkspace } from \"./suite-loader.ts\";\n\n/**\n * Bounded summary of the builtin plugin profile resolution: the `resolved`\n * variant carries id/version/digest/pluginIds; every other variant records the\n * variant name with its structured reason fields; an absent resolution is the\n * `none` variant. The full resolution objects stay with their existing\n * channels; the aggregate carries only this bounded projection.\n */\nexport type PluginProfileResolutionSummaryV1 =\n\t| {\n\t\t\treadonly variant: \"resolved\";\n\t\t\treadonly profileId: string;\n\t\t\treadonly profileVersion: string;\n\t\t\t/** Ecosystem resolved-manifests digest (suite-domain digest lives on `identity`). */\n\t\t\treadonly manifestDigest: string;\n\t\t\treadonly pluginIds: readonly string[];\n\t  }\n\t| { readonly variant: \"not_found\"; readonly profileId: string }\n\t| { readonly variant: \"host_facts_required\"; readonly profileId: string }\n\t| {\n\t\t\treadonly variant: \"invalid_selection\";\n\t\t\treadonly profileId: string;\n\t\t\treadonly unknownPluginIds: readonly string[];\n\t\t\treadonly duplicatePluginIds: readonly string[];\n\t  }\n\t| { readonly variant: \"none\" };\n\n/**\n * Unified diagnostic entry (D-047 S4d): each source keeps its own fidelity\n * behind a `source` tag — suite diagnostics are plain strings, plugin-profile\n * diagnostics keep their structured code/details. No lossy normalization.\n */\nexport type ResolvedProfileDiagnosticV1 =\n\t| { readonly source: \"suite\"; readonly message: string }\n\t| {\n\t\t\treadonly source: \"plugin-profile\";\n\t\t\treadonly code: PluginDiagnosticCodeV1;\n\t\t\treadonly message: string;\n\t\t\treadonly details?: Readonly<Record<string, string>>;\n\t  };\n\n/** The immutable, deep-frozen aggregate view of one session's resolved suite profile. */\nexport interface ResolvedAgentProfileV1 {\n\treadonly suiteId: string;\n\t/** Authoritative: workspace.identity (buildSuiteProfileIdentity product, already frozen). */\n\treadonly identity: ProfileIdentityV1;\n\t/** Authoritative: the verifyProfileLock three-state result; undefined when the workspace had no persisted lock. */\n\treadonly lockVerification?: ProfileLockVerificationV1;\n\t/** Bounded summary of the plugin profile resolution; never the live resolution objects. */\n\treadonly pluginProfile: PluginProfileResolutionSummaryV1;\n\t/** Bounded path projection of the suite workspace (no live objects). */\n\treadonly workspace: {\n\t\treadonly suiteDir: string;\n\t\treadonly suiteJsonPath: string;\n\t\treadonly agentsMdPath: string;\n\t\treadonly lockPath: string;\n\t};\n\t/**\n\t * Build-time diagnostic snapshot (D-047 S4d first increment): workspace\n\t * diagnostics (suite source, in order) followed by the resolved plugin\n\t * profile's diagnostics (plugin-profile source, in order). Empty when\n\t * neither source contributed — the common no-diagnostics case.\n\t */\n\treadonly diagnostics: readonly ResolvedProfileDiagnosticV1[];\n}\n\n/**\n * Builds the deep-frozen ResolvedAgentProfileV1 from the existing\n * authoritative sources. Pure function: it assembles from `input` and returns\n * a detached (deep-cloned, recursively frozen) snapshot, so later mutation of\n * the sources can never flow into the aggregate.\n */\nexport function buildResolvedAgentProfileV1(input: {\n\tsuiteId: string;\n\tworkspace: SuiteWorkspace;\n\tpluginProfile?: BuiltinPluginProfileResolutionV1;\n}): ResolvedAgentProfileV1 {\n\tconst { workspace } = input;\n\tconst pluginProfile = input.pluginProfile;\n\tconst summary: PluginProfileResolutionSummaryV1 =\n\t\tpluginProfile === undefined\n\t\t\t? { variant: \"none\" }\n\t\t\t: pluginProfile.status === \"resolved\"\n\t\t\t\t? {\n\t\t\t\t\t\tvariant: \"resolved\",\n\t\t\t\t\t\tprofileId: pluginProfile.profile.id,\n\t\t\t\t\t\tprofileVersion: pluginProfile.profile.version,\n\t\t\t\t\t\tmanifestDigest: pluginProfile.resolution.resolvedManifest.manifestDigest,\n\t\t\t\t\t\tpluginIds: pluginProfile.resolution.resolvedManifest.plugins.map((plugin) => plugin.pluginId),\n\t\t\t\t\t}\n\t\t\t\t: pluginProfile.status === \"invalid_selection\"\n\t\t\t\t\t? {\n\t\t\t\t\t\t\tvariant: \"invalid_selection\",\n\t\t\t\t\t\t\tprofileId: pluginProfile.profileId,\n\t\t\t\t\t\t\tunknownPluginIds: [...pluginProfile.unknownPluginIds],\n\t\t\t\t\t\t\tduplicatePluginIds: [...pluginProfile.duplicatePluginIds],\n\t\t\t\t\t\t}\n\t\t\t\t\t: pluginProfile.status === \"not_found\"\n\t\t\t\t\t\t? { variant: \"not_found\", profileId: pluginProfile.profileId }\n\t\t\t\t\t\t: { variant: \"host_facts_required\", profileId: pluginProfile.profileId };\n\tconst diagnostics: ResolvedProfileDiagnosticV1[] = [\n\t\t...workspace.diagnostics.map((message): ResolvedProfileDiagnosticV1 => ({ source: \"suite\", message })),\n\t\t...(pluginProfile?.status === \"resolved\"\n\t\t\t? pluginProfile.resolution.diagnostics.map(\n\t\t\t\t\t(diagnostic): ResolvedProfileDiagnosticV1 => ({\n\t\t\t\t\t\tsource: \"plugin-profile\",\n\t\t\t\t\t\tcode: diagnostic.code,\n\t\t\t\t\t\tmessage: diagnostic.message,\n\t\t\t\t\t\t...(diagnostic.details === undefined ? {} : { details: diagnostic.details }),\n\t\t\t\t\t}),\n\t\t\t\t)\n\t\t\t: []),\n\t];\n\treturn detachedSnapshot({\n\t\tsuiteId: input.suiteId,\n\t\tidentity: workspace.identity,\n\t\t...(workspace.lockVerification === undefined ? {} : { lockVerification: workspace.lockVerification }),\n\t\tpluginProfile: summary,\n\t\tworkspace: {\n\t\t\tsuiteDir: workspace.suiteDir,\n\t\t\tsuiteJsonPath: workspace.suiteJsonPath,\n\t\t\tagentsMdPath: workspace.agentsMdPath,\n\t\t\tlockPath: workspace.lockPath,\n\t\t},\n\t\tdiagnostics,\n\t});\n}\n"]}

package/dist/profiles/suite-lifecycle.d.ts

@@ -0,0 +1,158 @@
+import type { SettingsManager } from "../core/settings-manager.ts";
+import type { ProfileLockV1 } from "../profile/lock.ts";
+import { type SuiteDefinition } from "./builtin-suites.ts";
+export declare const SUITE_TRASH_DIR_NAME = ".trash";
+/** Trash retention for sweepSuiteTrash (M4 decision record). */
+export declare const DEFAULT_SUITE_TRASH_RETENTION_MS: number;
+/**
+ * Explicit programmatic authorization token for deleteSuite. The CLI confirms
+ * interactively before calling; programmatic callers pass this token to prove
+ * intent. Absent keeps the CLI-first flow working.
+ */
+export declare const SUITE_DELETE_CONFIRM_TOKEN = "suite-delete";
+/** lockedBy/authorizedBy stamped onto locks created by --suite-reset (2.7b). */
+export declare const SUITE_RESET_AUTHORIZED_BY = "suite-reset";
+export type SuiteLifecycleOperation = "create" | "delete" | "reset";
+/** Structured lifecycle refusal: operation, suite id, and every reason. */
+export declare class SuiteLifecycleError extends Error {
+    readonly operation: SuiteLifecycleOperation;
+    readonly suiteId: string;
+    readonly reasons: readonly string[];
+    constructor(operation: SuiteLifecycleOperation, suiteId: string, reasons: readonly string[]);
+}
+export interface SuiteCreateOptions {
+    readonly agentDir: string;
+    readonly id: string;
+    /** Clone an existing suite workspace (builtin or user) instead of a fresh skeleton. */
+    readonly cloneFrom?: string;
+    /** Display name; defaults to the id (fresh) or "<source name> clone" (cloned). */
+    readonly name?: string;
+    /** Injectable clock for the clonedFrom timestamp. */
+    readonly now?: () => number;
+}
+export interface SuiteCreateResult {
+    readonly suiteId: string;
+    readonly suiteDir: string;
+    readonly suiteJsonPath: string;
+    readonly definition: SuiteDefinition;
+}
+/**
+ * Creates a user suite workspace (设计 §9): `<agentDir>/suites/<id>/` with a
+ * suite.json plus an empty agents.md skeleton, or — with `cloneFrom` — a copy
+ * of the source workspace (effective definition, so a corrupted builtin
+ * source clones its factory content) with the suite.json identity rewritten:
+ * new id, `builtin: false`, and a `clonedFrom` record carrying the source id
+ * and the digest of the source's effective suite.json value. The source's
+ * `.profile-lock.json` is never copied: the clone is a new profile identity
+ * whose lock is created on first assembly.
+ */
+export declare function createSuite(options: SuiteCreateOptions): SuiteCreateResult;
+/** One existing session bound to a suite via its creation-time custom entry. */
+export interface SuiteSessionRef {
+    readonly path: string;
+    readonly sessionId: string;
+    readonly cwd: string | undefined;
+    readonly modified: Date;
+}
+/**
+ * Scans every session tree under `<agentDir>/sessions/<project>/*.jsonl` for
+ * sessions whose creation-time custom entry (customType "suite") binds them
+ * to `suiteId` (设计 §10.1). The suite entry sits in the first few lines of
+ * the file, so a bounded head scan (1 MB, matching the session header reader)
+ * is sufficient; a file whose binding line has been seen is decided — later
+ * lines cannot change it. Unreadable, oversized, or malformed files are
+ * skipped, never fatal. Custom session dirs (--session-dir) are out of scope.
+ */
+export declare function findSuiteSessionRefs(agentDir: string, suiteId: string): SuiteSessionRef[];
+export interface SuiteDeleteOptions {
+    readonly agentDir: string;
+    readonly id: string;
+    /** Session references from findSuiteSessionRefs; a non-empty list refuses the delete. */
+    readonly refs: readonly SuiteSessionRef[];
+    readonly now?: () => number;
+    /** Programmatic authorization; must equal SUITE_DELETE_CONFIRM_TOKEN when provided. */
+    readonly confirmToken?: string;
+    /**
+     * Memory purge hook (M5 wiring point): invoked after the workspace is
+     * isolated in the trash. M4 releases assets only; memory clearing goes
+     * through the Foundation purge gate once M5 lands.
+     */
+    readonly purgeMemories?: (suiteId: string) => void;
+}
+export interface SuiteDeleteResult {
+    readonly trashPath: string;
+}
+/**
+ * Moves a user suite workspace into `<agentDir>/suites/.trash/<id>-<UTC
+ * compact timestamp>-<random>/`. Builtin suites are refused; the workspace
+ * (directory + suite.json) must exist but does not need to parse; any
+ * session reference refuses the delete with the full list. The rename keeps
+ * the workspace recoverable; releaseTrashedSuite/sweepSuiteTrash do the
+ * actual removal.
+ */
+export declare function deleteSuite(options: SuiteDeleteOptions): SuiteDeleteResult;
+/**
+ * Fire-and-forget removal of one trash entry (Node's built-in Windows retry
+ * semantics). Failures never throw: the entry simply remains for the next
+ * sweepSuiteTrash run.
+ */
+export declare function releaseTrashedSuite(trashPath: string): void;
+export interface SuiteTrashSweepResult {
+    readonly removed: readonly string[];
+    readonly kept: readonly string[];
+}
+/**
+ * Removes trash entries older than `retentionMs` (default 7 days, per the M4
+ * decision record). Entries are aged by their mtime; unreadable entries are
+ * kept. Deterministic given the injectable clock.
+ */
+export declare function sweepSuiteTrash(agentDir: string, options?: {
+    retentionMs?: number;
+    now?: () => number;
+}): Promise<SuiteTrashSweepResult>;
+export interface SuiteResetApplyResult {
+    readonly suiteId: string;
+    /** Whether the on-disk suite.json differed from the factory contents. */
+    readonly wroteFactory: boolean;
+    /** The lock now persisted in the workspace. */
+    readonly lock: ProfileLockV1;
+    /** Defined when an existing lock was replaced via 2.7b applyMigration. */
+    readonly previousGeneration?: number;
+}
+export interface SuiteResetPlan {
+    readonly suiteId: string;
+    readonly factory: SuiteDefinition;
+    readonly suiteJsonPath: string;
+    readonly lockPath: string;
+    /** Display diff (edit-diff format) of the on-disk file vs the factory contents. */
+    readonly diffText: string;
+    /**
+     * Applies the reset: writes the factory suite.json, then persists the
+     * factory identity's lock. An existing lock goes through the 2.7b policy:
+     * `applyMigration` (authorizedBy "suite-reset") decides current vs
+     * non-current; a non-current lock is replaced via `replaceProfileLock`
+     * (generation increments, `previousGeneration` reports the swap). A missing
+     * or unreadable lock gets a fresh one. The replacement lock is evaluated
+     * before any write, so a failure leaves the previous files untouched.
+     */
+    apply(): SuiteResetApplyResult;
+}
+/**
+ * Plans a builtin suite reset (设计 §9 重置): diff the on-disk suite.json
+ * against the factory declaration without touching anything. User suites are
+ * refused — they have no factory contents to restore; remove them instead.
+ */
+export declare function resetSuite(options: {
+    agentDir: string;
+    id: string;
+    now?: () => number;
+}): SuiteResetPlan;
+export interface SuiteSettingsCleanup {
+    readonly clearedScopes: readonly ("project" | "global")[];
+}
+/**
+ * Clears the project/global settings `suite` keys when they point at `id`
+ * (设计 §9 删除连带). Keys pointing elsewhere are untouched.
+ */
+export declare function clearDanglingSuiteSettings(settingsManager: SettingsManager, id: string): SuiteSettingsCleanup;
+//# sourceMappingURL=suite-lifecycle.d.ts.map

package/dist/profiles/suite-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"suite-lifecycle.d.ts","sourceRoot":"","sources":["../../src/profiles/suite-lifecycle.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Suite lifecycle operations (方案系统设计.md v2 §9, M4): create/clone,\n * delete (trash + release + sweep), reset, session reference scan, and\n * dangling settings cleanup.\n *\n * Every operation is deterministic given its inputs (`now` is injectable) and\n * reports refusal reasons as structured errors. Deletion only ever renames\n * the workspace into the trash directory — release and sweep are separate,\n * re-runnable steps — so recovery stays possible until the trash is released.\n * Memory purge is intentionally a hook: the Foundation purge gate lands with\n * M5; before that only suite assets are released.\n */\nimport { randomUUID } from \"node:crypto\";\nimport {\n\tcloseSync,\n\tcpSync,\n\texistsSync,\n\tmkdirSync,\n\topenSync,\n\treaddirSync,\n\treadFileSync,\n\treadSync,\n\trenameSync,\n\tstatSync,\n\twriteFileSync,\n} from \"node:fs\";\nimport { readdir, rm, stat } from \"node:fs/promises\";\nimport { basename, join } from \"node:path\";\nimport { StringDecoder } from \"node:string_decoder\";\nimport type { SettingsManager } from \"../core/settings-manager.ts\";\nimport { generateDiffString } from \"../core/tools/edit-diff.ts\";\nimport type { ProfileLockV1 } from \"../profile/lock.ts\";\nimport { createProfileLock, replaceProfileLock } from \"../profile/lock.ts\";\nimport { createProfileMigrationPolicy } from \"../profile/profile-migration.ts\";\nimport {\n\tBUILTIN_SUITE_CAPABILITIES,\n\tBUILTIN_SUITE_TOOLS,\n\tDEFAULT_ROLE_ASSOCIATIONS,\n\tFACTORY_CONTENTS_VERSION,\n\tgetBuiltinSuite,\n\tisBuiltinSuiteId,\n\tisValidSuiteId,\n\tSUITE_SCHEMA_VERSION,\n\ttype SuiteDefinition,\n\tserializeSuiteJson,\n} from \"./builtin-suites.ts\";\nimport {\n\tbuildSuiteProfileIdentity,\n\tgetSuitesRootDir,\n\tgetSuiteWorkspaceDir,\n\tloadSuiteWorkspace,\n\tparseSuiteProfileLockFile,\n\tSUITE_AGENTS_MD_FILENAME,\n\tSUITE_LOCK_FILENAME,\n\tSUITE_MANIFEST_FILENAME,\n\tSUITE_SESSION_ENTRY_TYPE,\n\tSuiteResolutionError,\n\ttype SuiteWorkspace,\n\tserializeSuiteProfileLockFile,\n\tsuiteManifestDigest,\n} from \"./suite-loader.ts\";\n\nexport const SUITE_TRASH_DIR_NAME = \".trash\";\n/** Trash retention for sweepSuiteTrash (M4 decision record). */\nexport const DEFAULT_SUITE_TRASH_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;\n/**\n * Explicit programmatic authorization token for deleteSuite. The CLI confirms\n * interactively before calling; programmatic callers pass this token to prove\n * intent. Absent keeps the CLI-first flow working.\n */\nexport const SUITE_DELETE_CONFIRM_TOKEN = \"suite-delete\";\n/** lockedBy/authorizedBy stamped onto locks created by --suite-reset (2.7b). */\nexport const SUITE_RESET_AUTHORIZED_BY = \"suite-reset\";\n\nexport type SuiteLifecycleOperation = \"create\" | \"delete\" | \"reset\";\n\n/** Structured lifecycle refusal: operation, suite id, and every reason. */\nexport class SuiteLifecycleError extends Error {\n\treadonly operation: SuiteLifecycleOperation;\n\treadonly suiteId: string;\n\treadonly reasons: readonly string[];\n\n\tconstructor(operation: SuiteLifecycleOperation, suiteId: string, reasons: readonly string[]) {\n\t\tsuper(`Suite ${operation} failed for \"${suiteId}\": ${reasons.join(\"; \")}`);\n\t\tthis.name = \"SuiteLifecycleError\";\n\t\tthis.operation = operation;\n\t\tthis.suiteId = suiteId;\n\t\tthis.reasons = Object.freeze([...reasons]);\n\t}\n}\n\n// ---------------------------------------------------------------------------\n// Create / clone (设计 §9 创建)\n// ---------------------------------------------------------------------------\n\nexport interface SuiteCreateOptions {\n\treadonly agentDir: string;\n\treadonly id: string;\n\t/** Clone an existing suite workspace (builtin or user) instead of a fresh skeleton. */\n\treadonly cloneFrom?: string;\n\t/** Display name; defaults to the id (fresh) or \"<source name> clone\" (cloned). */\n\treadonly name?: string;\n\t/** Injectable clock for the clonedFrom timestamp. */\n\treadonly now?: () => number;\n}\n\nexport interface SuiteCreateResult {\n\treadonly suiteId: string;\n\treadonly suiteDir: string;\n\treadonly suiteJsonPath: string;\n\treadonly definition: SuiteDefinition;\n}\n\n/**\n * Creates a user suite workspace (设计 §9): `<agentDir>/suites/<id>/` with a\n * suite.json plus an empty agents.md skeleton, or — with `cloneFrom` — a copy\n * of the source workspace (effective definition, so a corrupted builtin\n * source clones its factory content) with the suite.json identity rewritten:\n * new id, `builtin: false`, and a `clonedFrom` record carrying the source id\n * and the digest of the source's effective suite.json value. The source's\n * `.profile-lock.json` is never copied: the clone is a new profile identity\n * whose lock is created on first assembly.\n */\nexport function createSuite(options: SuiteCreateOptions): SuiteCreateResult {\n\tconst { agentDir, id } = options;\n\tconst suiteDir = getSuiteWorkspaceDir(agentDir, id);\n\tconst suiteJsonPath = join(suiteDir, SUITE_MANIFEST_FILENAME);\n\n\tconst reasons: string[] = [];\n\tif (!isValidSuiteId(id)) {\n\t\treasons.push(\n\t\t\t`id must be a suite id (^[a-z0-9-]+$, no leading/trailing hyphen, Windows reserved names rejected), found ${JSON.stringify(id)}`,\n\t\t);\n\t}\n\tif (isBuiltinSuiteId(id)) {\n\t\treasons.push(\n\t\t\t`\"${id}\" is a builtin suite id; builtin workspaces are provisioned automatically and cannot be created`,\n\t\t);\n\t}\n\tif (existsSync(suiteDir)) {\n\t\treasons.push(`workspace directory ${suiteDir} already exists`);\n\t}\n\tif (reasons.length > 0) throw new SuiteLifecycleError(\"create\", id, reasons);\n\n\tlet definition: SuiteDefinition;\n\tif (options.cloneFrom === undefined) {\n\t\tdefinition = {\n\t\t\tschemaVersion: SUITE_SCHEMA_VERSION,\n\t\t\tid,\n\t\t\tname: options.name ?? id,\n\t\t\tbuiltin: false,\n\t\t\ttools: BUILTIN_SUITE_TOOLS,\n\t\t\tcapabilities: BUILTIN_SUITE_CAPABILITIES,\n\t\t\tassociations: { skills: [], mcp: [], plugins: [], roles: DEFAULT_ROLE_ASSOCIATIONS },\n\t\t\tinheritSystemAgentsMd: false,\n\t\t\tmemory: \"assistant\",\n\t\t\torientation: \"assistant\",\n\t\t\tmodel: null,\n\t\t\tthinking: null,\n\t\t\tclonedFrom: null,\n\t\t\tfactoryRevision: FACTORY_CONTENTS_VERSION,\n\t\t};\n\t\tmkdirSync(suiteDir, { recursive: true });\n\t\twriteFileSync(suiteJsonPath, serializeSuiteJson(definition), \"utf8\");\n\t\twriteFileSync(join(suiteDir, SUITE_AGENTS_MD_FILENAME), \"\", \"utf8\");\n\t} else {\n\t\tconst source = loadEffectiveSourceWorkspace(agentDir, options.cloneFrom);\n\t\tdefinition = {\n\t\t\t...source.suite,\n\t\t\tid,\n\t\t\tname: options.name ?? `${source.suite.name} clone`,\n\t\t\tbuiltin: false,\n\t\t\tclonedFrom: {\n\t\t\t\tid: source.suite.id,\n\t\t\t\tdigest: suiteManifestDigest(source.suite),\n\t\t\t\tat: options.now?.() ?? Date.now(),\n\t\t\t},\n\t\t\tfactoryRevision: FACTORY_CONTENTS_VERSION,\n\t\t};\n\t\t// Copy user assets (agents.md, skills, plugins, ...) but never the\n\t\t// source profile lock: the clone freezes its own identity on first\n\t\t// assembly.\n\t\tcpSync(source.suiteDir, suiteDir, {\n\t\t\trecursive: true,\n\t\t\tfilter: (sourcePath) => basename(sourcePath) !== SUITE_LOCK_FILENAME,\n\t\t});\n\t\twriteFileSync(suiteJsonPath, serializeSuiteJson(definition), \"utf8\");\n\t}\n\n\treturn { suiteId: id, suiteDir, suiteJsonPath, definition };\n}\n\nfunction loadEffectiveSourceWorkspace(agentDir: string, cloneFrom: string): SuiteWorkspace {\n\ttry {\n\t\treturn loadSuiteWorkspace({ agentDir, suiteId: cloneFrom });\n\t} catch (error) {\n\t\tif (error instanceof SuiteResolutionError) {\n\t\t\tthrow new SuiteLifecycleError(\"create\", cloneFrom, [`clone source \"${cloneFrom}\" does not exist`]);\n\t\t}\n\t\tthrow new SuiteLifecycleError(\"create\", cloneFrom, [\n\t\t\t`clone source \"${cloneFrom}\" is unusable: ${error instanceof Error ? error.message : String(error)}`,\n\t\t]);\n\t}\n}\n\n// ---------------------------------------------------------------------------\n// Session reference scan (设计 §9 删除前置检查)\n// ---------------------------------------------------------------------------\n\n/** One existing session bound to a suite via its creation-time custom entry. */\nexport interface SuiteSessionRef {\n\treadonly path: string;\n\treadonly sessionId: string;\n\treadonly cwd: string | undefined;\n\treadonly modified: Date;\n}\n\n/** Bounded head-scan window, aligned with the session header reader (1 MB). */\nconst SUITE_REF_SCAN_LIMIT_BYTES = 1024 * 1024;\nconst SUITE_REF_READ_BUFFER_SIZE = 64 * 1024;\n\ninterface SuiteRefScanOutcome {\n\treadonly sessionId: string | undefined;\n\treadonly cwd: string | undefined;\n\treadonly bound: boolean;\n}\n\n/**\n * Scans every session tree under `<agentDir>/sessions/<project>/*.jsonl` for\n * sessions whose creation-time custom entry (customType \"suite\") binds them\n * to `suiteId` (设计 §10.1). The suite entry sits in the first few lines of\n * the file, so a bounded head scan (1 MB, matching the session header reader)\n * is sufficient; a file whose binding line has been seen is decided — later\n * lines cannot change it. Unreadable, oversized, or malformed files are\n * skipped, never fatal. Custom session dirs (--session-dir) are out of scope.\n */\nexport function findSuiteSessionRefs(agentDir: string, suiteId: string): SuiteSessionRef[] {\n\tconst sessionsDir = join(agentDir, \"sessions\");\n\tif (!existsSync(sessionsDir)) return [];\n\tconst refs: SuiteSessionRef[] = [];\n\tfor (const projectEntry of readdirSync(sessionsDir, { withFileTypes: true })) {\n\t\tif (!projectEntry.isDirectory()) continue;\n\t\tconst projectDir = join(sessionsDir, projectEntry.name);\n\t\tlet files: string[];\n\t\ttry {\n\t\t\tfiles = readdirSync(projectDir).filter((file) => file.endsWith(\".jsonl\"));\n\t\t} catch {\n\t\t\tcontinue;\n\t\t}\n\t\tfor (const file of files) {\n\t\t\tconst path = join(projectDir, file);\n\t\t\ttry {\n\t\t\t\tconst outcome = scanSessionFileForSuiteBinding(path, suiteId);\n\t\t\t\tif (outcome.bound && outcome.sessionId !== undefined) {\n\t\t\t\t\trefs.push({\n\t\t\t\t\t\tpath,\n\t\t\t\t\t\tsessionId: outcome.sessionId,\n\t\t\t\t\t\tcwd: outcome.cwd,\n\t\t\t\t\t\tmodified: statSync(path).mtime,\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t} catch {\n\t\t\t\t// Skip unreadable files; one bad file must not block deletion.\n\t\t\t}\n\t\t}\n\t}\n\treturn refs;\n}\n\nfunction scanSessionFileForSuiteBinding(path: string, suiteId: string): SuiteRefScanOutcome {\n\tconst fd = openSync(path, \"r\");\n\ttry {\n\t\tconst decoder = new StringDecoder(\"utf8\");\n\t\tconst buffer = Buffer.allocUnsafe(SUITE_REF_READ_BUFFER_SIZE);\n\t\tlet scannedBytes = 0;\n\t\tlet sessionId: string | undefined;\n\t\tlet cwd: string | undefined;\n\t\tlet leftover = \"\";\n\t\tlet bound = false;\n\t\tlet bindingDecided = false;\n\n\t\twhile (scannedBytes < SUITE_REF_SCAN_LIMIT_BYTES && !bindingDecided) {\n\t\t\tconst readLength = Math.min(buffer.length, SUITE_REF_SCAN_LIMIT_BYTES - scannedBytes);\n\t\t\tconst bytesRead = readSync(fd, buffer, 0, readLength, null);\n\t\t\tif (bytesRead === 0) break;\n\t\t\tscannedBytes += bytesRead;\n\t\t\tconst chunk = leftover + decoder.write(buffer.subarray(0, bytesRead));\n\t\t\tconst lines = chunk.split(\"\\n\");\n\t\t\tleftover = lines.pop() ?? \"\";\n\t\t\tfor (const line of lines) {\n\t\t\t\tconst entry = parseSuiteRefLine(line);\n\t\t\t\tif (entry === undefined) continue;\n\t\t\t\tif (entry.header !== undefined && sessionId === undefined) {\n\t\t\t\t\tsessionId = entry.header.id;\n\t\t\t\t\tcwd = entry.header.cwd;\n\t\t\t\t}\n\t\t\t\tif (entry.boundToSuite !== undefined) {\n\t\t\t\t\tbound = entry.boundToSuite === suiteId;\n\t\t\t\t\tbindingDecided = true;\n\t\t\t\t\tbreak;\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\treturn { sessionId, cwd, bound };\n\t} finally {\n\t\tcloseSync(fd);\n\t}\n}\n\ninterface SuiteRefLineParseResult {\n\treadonly header?: { readonly id: string; readonly cwd: string | undefined };\n\t/** The suite id this session is bound to, when the line is the suite binding entry. */\n\treadonly boundToSuite?: string;\n}\n\nfunction parseSuiteRefLine(line: string): SuiteRefLineParseResult | undefined {\n\tconst trimmed = line.trim();\n\tif (trimmed.length === 0) return undefined;\n\tlet value: unknown;\n\ttry {\n\t\tvalue = JSON.parse(trimmed);\n\t} catch {\n\t\treturn undefined;\n\t}\n\tif (value === null || typeof value !== \"object\" || Array.isArray(value)) return undefined;\n\tconst record = value as Record<string, unknown>;\n\tif (record.type === \"session\" && typeof record.id === \"string\") {\n\t\treturn { header: { id: record.id, cwd: typeof record.cwd === \"string\" ? record.cwd : undefined } };\n\t}\n\tif (record.type === \"custom\" && record.customType === SUITE_SESSION_ENTRY_TYPE) {\n\t\tconst data = record.data;\n\t\tconst suiteId =\n\t\t\tdata !== null && typeof data === \"object\" && typeof (data as Record<string, unknown>).suiteId === \"string\"\n\t\t\t\t? ((data as Record<string, unknown>).suiteId as string)\n\t\t\t\t: undefined;\n\t\treturn suiteId === undefined ? {} : { boundToSuite: suiteId };\n\t}\n\treturn {};\n}\n\n// ---------------------------------------------------------------------------\n// Delete: trash rename, release, sweep (设计 §9 删除)\n// ---------------------------------------------------------------------------\n\nexport interface SuiteDeleteOptions {\n\treadonly agentDir: string;\n\treadonly id: string;\n\t/** Session references from findSuiteSessionRefs; a non-empty list refuses the delete. */\n\treadonly refs: readonly SuiteSessionRef[];\n\treadonly now?: () => number;\n\t/** Programmatic authorization; must equal SUITE_DELETE_CONFIRM_TOKEN when provided. */\n\treadonly confirmToken?: string;\n\t/**\n\t * Memory purge hook (M5 wiring point): invoked after the workspace is\n\t * isolated in the trash. M4 releases assets only; memory clearing goes\n\t * through the Foundation purge gate once M5 lands.\n\t */\n\treadonly purgeMemories?: (suiteId: string) => void;\n}\n\nexport interface SuiteDeleteResult {\n\treadonly trashPath: string;\n}\n\n/**\n * Moves a user suite workspace into `<agentDir>/suites/.trash/<id>-<UTC\n * compact timestamp>-<random>/`. Builtin suites are refused; the workspace\n * (directory + suite.json) must exist but does not need to parse; any\n * session reference refuses the delete with the full list. The rename keeps\n * the workspace recoverable; releaseTrashedSuite/sweepSuiteTrash do the\n * actual removal.\n */\nexport function deleteSuite(options: SuiteDeleteOptions): SuiteDeleteResult {\n\tconst { agentDir, id } = options;\n\tif (options.confirmToken !== undefined && options.confirmToken !== SUITE_DELETE_CONFIRM_TOKEN) {\n\t\tthrow new SuiteLifecycleError(\"delete\", id, [\n\t\t\t`confirmToken must be \"${SUITE_DELETE_CONFIRM_TOKEN}\" when provided`,\n\t\t]);\n\t}\n\tconst reasons: string[] = [];\n\tif (isBuiltinSuiteId(id)) {\n\t\treasons.push(`builtin suite \"${id}\" cannot be deleted`);\n\t}\n\tconst suiteDir = getSuiteWorkspaceDir(agentDir, id);\n\tconst suiteJsonPath = join(suiteDir, SUITE_MANIFEST_FILENAME);\n\tif (!existsSync(suiteDir)) {\n\t\treasons.push(`workspace directory ${suiteDir} does not exist`);\n\t} else if (!existsSync(suiteJsonPath)) {\n\t\treasons.push(`${suiteJsonPath} does not exist`);\n\t}\n\tif (reasons.length > 0) throw new SuiteLifecycleError(\"delete\", id, reasons);\n\n\tif (options.refs.length > 0) {\n\t\tthrow new SuiteLifecycleError(\n\t\t\t\"delete\",\n\t\t\tid,\n\t\t\toptions.refs.map((ref) => `session ${ref.sessionId} at ${ref.path} references this suite`),\n\t\t);\n\t}\n\n\tconst trashRoot = join(getSuitesRootDir(agentDir), SUITE_TRASH_DIR_NAME);\n\tmkdirSync(trashRoot, { recursive: true });\n\tconst trashPath = join(\n\t\ttrashRoot,\n\t\t`${id}-${formatTrashTimestamp(options.now?.() ?? Date.now())}-${randomUUID().replaceAll(\"-\", \"\").slice(0, 6)}`,\n\t);\n\trenameSync(suiteDir, trashPath);\n\toptions.purgeMemories?.(id);\n\treturn { trashPath };\n}\n\nfunction formatTrashTimestamp(ms: number): string {\n\t// UTC compact, sortable: \"20260907T123456789Z\".\n\treturn new Date(ms).toISOString().replace(/[-:]/g, \"\").replace(\".\", \"\");\n}\n\n/**\n * Fire-and-forget removal of one trash entry (Node's built-in Windows retry\n * semantics). Failures never throw: the entry simply remains for the next\n * sweepSuiteTrash run.\n */\nexport function releaseTrashedSuite(trashPath: string): void {\n\tvoid rm(trashPath, { recursive: true, force: true, maxRetries: 5, retryDelay: 100 }).catch(() => {\n\t\t// Left for sweepSuiteTrash; release is re-runnable by structure.\n\t});\n}\n\nexport interface SuiteTrashSweepResult {\n\treadonly removed: readonly string[];\n\treadonly kept: readonly string[];\n}\n\n/**\n * Removes trash entries older than `retentionMs` (default 7 days, per the M4\n * decision record). Entries are aged by their mtime; unreadable entries are\n * kept. Deterministic given the injectable clock.\n */\nexport async function sweepSuiteTrash(\n\tagentDir: string,\n\toptions: { retentionMs?: number; now?: () => number } = {},\n): Promise<SuiteTrashSweepResult> {\n\tconst trashRoot = join(getSuitesRootDir(agentDir), SUITE_TRASH_DIR_NAME);\n\tconst retentionMs = options.retentionMs ?? DEFAULT_SUITE_TRASH_RETENTION_MS;\n\tconst cutoffMs = (options.now?.() ?? Date.now()) - retentionMs;\n\tconst removed: string[] = [];\n\tconst kept: string[] = [];\n\tlet entryNames: string[];\n\ttry {\n\t\tentryNames = await readdir(trashRoot);\n\t} catch {\n\t\treturn { removed: Object.freeze(removed), kept: Object.freeze(kept) };\n\t}\n\tfor (const name of entryNames) {\n\t\tconst entryPath = join(trashRoot, name);\n\t\ttry {\n\t\t\tconst stats = await stat(entryPath);\n\t\t\tif (stats.mtimeMs <= cutoffMs) {\n\t\t\t\tawait rm(entryPath, { recursive: true, force: true });\n\t\t\t\tremoved.push(name);\n\t\t\t} else {\n\t\t\t\tkept.push(name);\n\t\t\t}\n\t\t} catch {\n\t\t\tkept.push(name);\n\t\t}\n\t}\n\treturn { removed: Object.freeze(removed), kept: Object.freeze(kept) };\n}\n\n// ---------------------------------------------------------------------------\n// Reset (设计 §9 重置): factory contents + authorized lock migration (2.7b)\n// ---------------------------------------------------------------------------\n\nexport interface SuiteResetApplyResult {\n\treadonly suiteId: string;\n\t/** Whether the on-disk suite.json differed from the factory contents. */\n\treadonly wroteFactory: boolean;\n\t/** The lock now persisted in the workspace. */\n\treadonly lock: ProfileLockV1;\n\t/** Defined when an existing lock was replaced via 2.7b applyMigration. */\n\treadonly previousGeneration?: number;\n}\n\nexport interface SuiteResetPlan {\n\treadonly suiteId: string;\n\treadonly factory: SuiteDefinition;\n\treadonly suiteJsonPath: string;\n\treadonly lockPath: string;\n\t/** Display diff (edit-diff format) of the on-disk file vs the factory contents. */\n\treadonly diffText: string;\n\t/**\n\t * Applies the reset: writes the factory suite.json, then persists the\n\t * factory identity's lock. An existing lock goes through the 2.7b policy:\n\t * `applyMigration` (authorizedBy \"suite-reset\") decides current vs\n\t * non-current; a non-current lock is replaced via `replaceProfileLock`\n\t * (generation increments, `previousGeneration` reports the swap). A missing\n\t * or unreadable lock gets a fresh one. The replacement lock is evaluated\n\t * before any write, so a failure leaves the previous files untouched.\n\t */\n\tapply(): SuiteResetApplyResult;\n}\n\n/**\n * Plans a builtin suite reset (设计 §9 重置): diff the on-disk suite.json\n * against the factory declaration without touching anything. User suites are\n * refused — they have no factory contents to restore; remove them instead.\n */\nexport function resetSuite(options: { agentDir: string; id: string; now?: () => number }): SuiteResetPlan {\n\tconst { agentDir, id } = options;\n\tconst factory = getBuiltinSuite(id);\n\tif (factory === undefined) {\n\t\tthrow new SuiteLifecycleError(\"reset\", id, [\n\t\t\tisBuiltinSuiteId(id)\n\t\t\t\t? `builtin suite \"${id}\" has no factory declaration`\n\t\t\t\t: `suite \"${id}\" is not builtin; only builtin suites can be reset — delete user suites instead`,\n\t\t]);\n\t}\n\tconst suiteDir = getSuiteWorkspaceDir(agentDir, id);\n\tconst suiteJsonPath = join(suiteDir, SUITE_MANIFEST_FILENAME);\n\tconst lockPath = join(suiteDir, SUITE_LOCK_FILENAME);\n\tconst factoryJson = serializeSuiteJson(factory);\n\tconst currentRaw = existsSync(suiteJsonPath) ? readFileSync(suiteJsonPath, \"utf8\") : \"\";\n\n\tconst apply = (): SuiteResetApplyResult => {\n\t\tconst identity = buildSuiteProfileIdentity(factory);\n\t\t// Evaluate the replacement before any write (2.7b): a failure above this\n\t\t// point leaves the previous suite.json and lock untouched.\n\t\tlet previousLock: ProfileLockV1 | undefined;\n\t\tif (existsSync(lockPath)) {\n\t\t\ttry {\n\t\t\t\tpreviousLock = parseSuiteProfileLockFile(readFileSync(lockPath, \"utf8\"));\n\t\t\t} catch {\n\t\t\t\tpreviousLock = undefined;\n\t\t\t}\n\t\t}\n\t\tlet lock: ProfileLockV1;\n\t\tlet previousGeneration: number | undefined;\n\t\tlet replaced = false;\n\t\tif (previousLock !== undefined) {\n\t\t\t// Explicit authorized migration (2.7b): applyMigration decides whether\n\t\t\t// the stored lock is already current; only a non-current outcome\n\t\t\t// replaces the lock, through replaceProfileLock — the lock's only\n\t\t\t// authorized swap primitive (generation increments).\n\t\t\tconst policy = createProfileMigrationPolicy();\n\t\t\tconst migration = policy.applyMigration({\n\t\t\t\tlock: previousLock,\n\t\t\t\tcurrent: identity,\n\t\t\t\tauthorizedBy: SUITE_RESET_AUTHORIZED_BY,\n\t\t\t\t...(options.now === undefined ? {} : { now: options.now }),\n\t\t\t});\n\t\t\tif (migration.status === \"failed\") {\n\t\t\t\tthrow new SuiteLifecycleError(\"reset\", id, [migration.reason]);\n\t\t\t}\n\t\t\tif (migration.status === \"current\") {\n\t\t\t\tlock = previousLock;\n\t\t\t} else {\n\t\t\t\tconst swap = replaceProfileLock(\n\t\t\t\t\tpreviousLock,\n\t\t\t\t\tidentity,\n\t\t\t\t\t{ authorizedBy: SUITE_RESET_AUTHORIZED_BY },\n\t\t\t\t\toptions.now === undefined ? {} : { now: options.now },\n\t\t\t\t);\n\t\t\t\tlock = swap.lock;\n\t\t\t\tpreviousGeneration = swap.previousGeneration;\n\t\t\t\treplaced = true;\n\t\t\t}\n\t\t} else {\n\t\t\tlock = createProfileLock(identity, {\n\t\t\t\tlockedBy: SUITE_RESET_AUTHORIZED_BY,\n\t\t\t\t...(options.now === undefined ? {} : { now: options.now }),\n\t\t\t});\n\t\t\treplaced = true;\n\t\t}\n\t\t// The workspace may never have been assembled (first assembly provisions\n\t\t// it, loadSuiteWorkspace-style); create the directory so a reset of a\n\t\t// never-assembled builtin does not fail with a bare ENOENT.\n\t\tmkdirSync(suiteDir, { recursive: true });\n\t\twriteFileSync(suiteJsonPath, factoryJson, \"utf8\");\n\t\t// D-075 S4 第三批：reset 不再预种角色文件——种子由 subagent-delegate 插件\n\t\t// 注册期的幂等补缺承担（见 entry.ts）；方案重置只重写方案自身内容。\n\t\tif (replaced || previousLock === undefined) {\n\t\t\twriteFileSync(lockPath, serializeSuiteProfileLockFile(lock), \"utf8\");\n\t\t}\n\t\treturn {\n\t\t\tsuiteId: id,\n\t\t\twroteFactory: currentRaw !== factoryJson,\n\t\t\tlock,\n\t\t\t...(previousGeneration === undefined ? {} : { previousGeneration }),\n\t\t};\n\t};\n\n\treturn {\n\t\tsuiteId: id,\n\t\tfactory,\n\t\tsuiteJsonPath,\n\t\tlockPath,\n\t\tdiffText: generateDiffString(currentRaw, factoryJson).diff,\n\t\tapply,\n\t};\n}\n\n// ---------------------------------------------------------------------------\n// Dangling settings cleanup (设计 §9 删除连带)\n// ---------------------------------------------------------------------------\n\nexport interface SuiteSettingsCleanup {\n\treadonly clearedScopes: readonly (\"project\" | \"global\")[];\n}\n\n/**\n * Clears the project/global settings `suite` keys when they point at `id`\n * (设计 §9 删除连带). Keys pointing elsewhere are untouched.\n */\nexport function clearDanglingSuiteSettings(settingsManager: SettingsManager, id: string): SuiteSettingsCleanup {\n\tconst clearedScopes: (\"project\" | \"global\")[] = [];\n\tif (settingsManager.getProjectSettings().suite === id) {\n\t\tsettingsManager.setProjectSuite(undefined);\n\t\tclearedScopes.push(\"project\");\n\t}\n\tif (settingsManager.getGlobalSettings().suite === id) {\n\t\tsettingsManager.setSuite(undefined);\n\t\tclearedScopes.push(\"global\");\n\t}\n\treturn { clearedScopes: Object.freeze(clearedScopes) };\n}\n"]}