synomem 0.3.0 → 0.4.0

package/src/client.ts

@@ -106,7 +106,11 @@ export interface SynomemCoreOptions {
 }
 
 export class SynomemCore implements SynomemDomainService {
-  readonly actor: ActorIdentity;
+  /**
+   * Mutable because an agent actor is resolved to its canonical identity on
+   * init: callers name a handle, events record the opaque ID.
+   */
+  actor: ActorIdentity;
   private readonly repository: SynomemRepository;
   private readonly projectionWriter: ProjectionWriter;
   private readonly clock: () => Date;
@@ -121,6 +125,11 @@ export class SynomemCore implements SynomemDomainService {
     get: (idOrAlias: string) => this.getAgent(idOrAlias),
     list: () => this.listAgents(),
     resolve: (query: string) => this.resolveAgent(query),
+    archive: (idOrAlias: string) => this.setAgentStatus(idOrAlias, 'archived'),
+    restore: (idOrAlias: string) => this.setAgentStatus(idOrAlias, 'active'),
+    addAliases: (idOrAlias: string, aliases: string[]) => this.addAgentAliases(idOrAlias, aliases),
+    removeAliases: (idOrAlias: string, aliases: string[]) =>
+      this.removeAgentAliases(idOrAlias, aliases),
     directory: () => this.agentDirectory(),
     bindings: (idOrAlias: string) => this.listRuntimeBindings(idOrAlias),
     bindRuntime: (input: BindRuntimeInput) => this.bindRuntime(input),
@@ -271,6 +280,30 @@ export class SynomemCore implements SynomemDomainService {
     if (this.initialized) return;
     await this.repository.init();
     this.initialized = true;
+
+    /*
+     * An agent actor is resolved to its canonical identity here.
+     *
+     * Callers name a handle because that is what people and harnesses know,
+     * but every event must record the opaque ID — otherwise renaming a handle
+     * would orphan the history written under the old one. The display name
+     * comes from the profile for the same reason a harness cannot assert it on
+     * the command line: the stored record is the authority, not the argument.
+     *
+     * An unresolvable name is left as given rather than rejected, so a system
+     * actor can still create the agent that does not exist yet. Writing as an
+     * unknown agent is refused later by the checks that already exist.
+     */
+    if (this.actor.kind === 'agent') {
+      const resolved = await this.repository.resolveAgent(this.actor.id);
+      if (resolved.match) {
+        this.actor = {
+          kind: 'agent',
+          id: resolved.match.id,
+          ...(resolved.match.displayName ? { displayName: resolved.match.displayName } : {}),
+        };
+      }
+    }
   }
 
   async close(): Promise<void> {
@@ -314,20 +347,29 @@ export class SynomemCore implements SynomemDomainService {
     this.checkAbort();
     await this.repository.assertEventCompatibility();
     const parsed = this.validate(() => createAgentSchema.parse(input));
-    if (await this.repository.getAgent(parsed.id)) {
-      throw new SynomemError('AGENT_EXISTS', `Agent or alias already exists: ${parsed.id}`);
+    if (await this.repository.getAgent(parsed.handle)) {
+      throw new SynomemError('AGENT_EXISTS', `Agent or alias already exists: ${parsed.handle}`);
     }
     const aliases = [...new Set(parsed.aliases ?? [])].sort();
-    if (aliases.includes(parsed.id)) {
-      throw new SynomemError('ALIAS_CONFLICT', 'An agent cannot use its own ID as an alias.');
+    if (aliases.includes(parsed.handle)) {
+      throw new SynomemError('ALIAS_CONFLICT', 'An agent cannot use its own handle as an alias.');
     }
     for (const alias of aliases) {
       if (await this.repository.getAgent(alias)) {
         throw new SynomemError('ALIAS_CONFLICT', `Alias already belongs to an agent: ${alias}`);
       }
     }
+    /*
+     * The canonical ID is generated here and never supplied by the caller.
+     * Every event references it permanently, so it has to be free of meaning:
+     * a caller that could choose it could choose one that collides with an
+     * archived agent's history, and a meaningful ID becomes a handle nobody can
+     * rename.
+     */
     const profile: AgentProfile = {
-      id: parsed.id,
+      id: this.nextId(),
+      handle: parsed.handle,
+      status: 'active',
       displayName: parsed.displayName,
       ...(aliases.length ? { aliases } : {}),
       ...(parsed.description !== undefined ? { description: parsed.description } : {}),
@@ -355,8 +397,20 @@ export class SynomemCore implements SynomemDomainService {
     const existing = await this.repository.getAgent(idOrAlias);
     if (!existing) throw new SynomemError('AGENT_NOT_FOUND', `Unknown agent: ${idOrAlias}`);
     const aliases = parsed.aliases ? [...new Set(parsed.aliases)].sort() : existing.aliases;
-    if (aliases?.includes(existing.id)) {
-      throw new SynomemError('ALIAS_CONFLICT', 'An agent cannot use its own ID as an alias.');
+    const handle = parsed.handle ?? existing.handle;
+    if (aliases?.includes(handle)) {
+      throw new SynomemError('ALIAS_CONFLICT', 'An agent cannot use its own handle as an alias.');
+    }
+    // Renaming the handle is allowed and is why the canonical ID exists, but a
+    // handle another agent already answers to is still refused.
+    if (parsed.handle && parsed.handle !== existing.handle) {
+      const owner = await this.repository.getAgent(parsed.handle);
+      if (owner && owner.id !== existing.id) {
+        throw new SynomemError(
+          'ALIAS_CONFLICT',
+          `Handle already belongs to ${owner.id}: ${parsed.handle}`,
+        );
+      }
     }
     for (const alias of aliases ?? []) {
       const owner = await this.repository.getAgent(alias);
@@ -384,6 +438,52 @@ export class SynomemCore implements SynomemDomainService {
     return updated;
   }
 
+  /**
+   * Archiving stops an agent acting without erasing it.
+   *
+   * Events reference the actor permanently, so deleting an agent would leave
+   * history pointing at nothing. Archived agents keep their records and their
+   * handle, and can be restored.
+   */
+  private async setAgentStatus(
+    idOrAlias: string,
+    status: 'active' | 'archived',
+  ): Promise<AgentProfile> {
+    this.checkAbort();
+    await this.repository.assertEventCompatibility();
+    this.validate(() => agentLookupSchema.parse(idOrAlias));
+    const existing = await this.repository.getAgent(idOrAlias);
+    if (!existing) throw new SynomemError('AGENT_NOT_FOUND', `Unknown agent: ${idOrAlias}`);
+    if (existing.status === status) return existing;
+    const updated: AgentProfile = { ...existing, status };
+    await this.repository.transaction(async () => {
+      const event: SynomemEvent = {
+        ...this.eventBase(existing.id, await this.repository.nextAggregateVersion(existing.id)),
+        type: 'agent.updated',
+        agentId: existing.id,
+        changes: { status },
+      };
+      await this.repository.updateAgent(updated, event.createdAt);
+      await this.repository.insertEvent(event);
+    });
+    await this.projectionWriter.syncAgent(updated.id);
+    return updated;
+  }
+
+  /** Adds aliases without disturbing the ones already there. */
+  private async addAgentAliases(idOrAlias: string, add: string[]): Promise<AgentProfile> {
+    const existing = await this.getAgent(idOrAlias);
+    const merged = [...new Set([...(existing.aliases ?? []), ...add])].sort();
+    return await this.updateAgent(existing.id, { aliases: merged });
+  }
+
+  private async removeAgentAliases(idOrAlias: string, remove: string[]): Promise<AgentProfile> {
+    const existing = await this.getAgent(idOrAlias);
+    const drop = new Set(remove.map((alias) => alias.trim().toLowerCase()));
+    const kept = (existing.aliases ?? []).filter((alias) => !drop.has(alias));
+    return await this.updateAgent(existing.id, { aliases: kept });
+  }
+
   private async getAgent(idOrAlias: string): Promise<AgentProfile> {
     this.checkAbort();
     this.validate(() => agentLookupSchema.parse(idOrAlias));
@@ -1441,10 +1541,34 @@ export class SynomemCore implements SynomemDomainService {
     return await this.getTodoRecord(input.todoId);
   }
 
+  /**
+   * Turns an agent name in a filter into the canonical ID the records hold.
+   *
+   * Callers filter by the name they know — a handle or an alias — while every
+   * record stores the opaque ID. Without this the filter silently matches
+   * nothing, which reads as "there is nothing here" rather than "that name
+   * means something else now".
+   *
+   * An unresolvable name is passed through unchanged so it can match a legacy
+   * name-shaped ID rather than being swallowed.
+   */
+  private async canonicalAgentId(name: string | undefined): Promise<string | undefined> {
+    if (!name) return name;
+    const resolved = await this.repository.resolveAgent(name);
+    return resolved.match?.id ?? name;
+  }
+
   private async listItems(input: ItemListInput): Promise<Page<ItemSummary>> {
     this.checkAbort();
     const parsed = this.validate(() => itemListInputSchema.parse(input));
-    return await this.repository.listItemSummaries(parsed, this.actor);
+    const resolved = {
+      ...parsed,
+      ...(parsed.participantAgentId
+        ? { participantAgentId: await this.canonicalAgentId(parsed.participantAgentId) }
+        : {}),
+      ...(parsed.actorId ? { actorId: await this.canonicalAgentId(parsed.actorId) } : {}),
+    };
+    return await this.repository.listItemSummaries(resolved, this.actor);
   }
   private async listItemChanges(input: ChangesInput): Promise<ChangePage> {
     this.checkAbort();
@@ -1539,8 +1663,8 @@ export class SynomemCore implements SynomemDomainService {
  * check that silently lags the migration runner reports a healthy database as
  * broken.
  */
-const CURRENT_SCHEMA_VERSION = 6;
-const EXPECTED_APPLIED_MIGRATIONS = [1, 2, 3, 4, 5, 6];
+const CURRENT_SCHEMA_VERSION = 7;
+const EXPECTED_APPLIED_MIGRATIONS = [1, 2, 3, 4, 5, 6, 7];
 
 export class SynomemClient extends SynomemCore implements SynomemService {
   readonly home: string;

package/src/cloud.ts

@@ -0,0 +1,19 @@
+/**
+ * Synomem Cloud, as a constant rather than a question.
+ *
+ * Public onboarding must never ask for a service URL. A person setting up
+ * Synomem has no way to know whether an address they were given is the real
+ * one, and a prompt that accepts any origin is a prompt that can be phished.
+ * The hosted service therefore has one address, compiled in.
+ *
+ * `SYNOMEM_API_URL` remains for development and private deployments. It is
+ * deliberately undocumented in the README, the public docs, the packaged skill
+ * and ordinary help output — a private deployment is configured by whoever runs
+ * it, not discovered by an ordinary user.
+ */
+export const SYNOMEM_CLOUD_API_URL = 'https://api.synomem.ai';
+
+export function cloudApiUrl(env: NodeJS.ProcessEnv = process.env): string {
+  const override = env.SYNOMEM_API_URL?.trim();
+  return override || SYNOMEM_CLOUD_API_URL;
+}

package/src/config.ts

@@ -73,7 +73,14 @@ export const configSchema = policySchema.extend({
 });
 
 export function resolveHome(explicitHome?: string): string {
-  const candidate = explicitHome ?? process.env.SYNOMEM_HOME ?? resolve(homedir(), '.agents');
+  /*
+   * `~/.synomem`, resolved as an exact directory.
+   *
+   * No detection of or migration from `~/.agents`: the project is greenfield,
+   * and code that quietly moves somebody's database is worse than a clear
+   * message telling them where the new home is.
+   */
+  const candidate = explicitHome ?? process.env.SYNOMEM_HOME ?? resolve(homedir(), '.synomem');
   if (candidate.includes('\0')) throw new SynomemError('UNSAFE_PATH', 'Storage home contains NUL.');
   return resolve(candidate);
 }

package/src/configure.ts

@@ -0,0 +1,233 @@
+/**
+ * `synomem config` — the onboarding wizard, and its deterministic equivalent.
+ *
+ * Two rules shape this file. Every interactive step has a non-interactive
+ * counterpart, so an agent can configure a machine without a terminal. And the
+ * wizard refuses to run at all when nobody is there to answer: a setup program
+ * that blocks forever on a pipe is worse than one that says which flags it
+ * needs.
+ */
+import { chmodSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { cloudApiUrl } from './cloud.js';
+import { SynomemError } from './errors.js';
+import { resolveHome } from './config.js';
+import { ask, askSecret, confirm, select, type PromptIo } from './prompt.js';
+
+export type BackendChoice = 'local' | 'remote';
+export type AuthChoice = 'browser' | 'access-key';
+export type CredentialStoreChoice = 'auto' | 'keychain' | 'file' | 'environment';
+
+export interface ConfigInitOptions {
+  backend?: BackendChoice;
+  home?: string;
+  auth?: AuthChoice;
+  workspace?: string;
+  accessToken?: string;
+  credentialStore?: CredentialStoreChoice;
+  yes?: boolean;
+}
+
+export interface ConfigPlan {
+  backend: BackendChoice;
+  home: string;
+  serviceUrl?: string;
+  auth?: AuthChoice;
+  workspaceId?: string;
+  credentialStore?: CredentialStoreChoice;
+}
+
+/**
+ * Where a credential can actually be kept on this platform.
+ *
+ * Reported rather than assumed: offering macOS Keychain on Linux, or a Secret
+ * Service that is not running, produces a setup that appears to succeed and
+ * then cannot read its own credential back.
+ */
+export function credentialStoreChoices(
+  platform: NodeJS.Platform = process.platform,
+): Array<{ value: CredentialStoreChoice; label: string; detail?: string }> {
+  const native =
+    platform === 'darwin'
+      ? { value: 'keychain' as const, label: 'macOS Keychain', detail: 'Recommended.' }
+      : platform === 'win32'
+        ? {
+            value: 'keychain' as const,
+            label: 'Windows Credential Manager',
+            detail: 'Recommended.',
+          }
+        : {
+            value: 'keychain' as const,
+            label: 'Secret Service (libsecret)',
+            detail: 'Recommended where a desktop keyring is running.',
+          };
+  return [
+    native,
+    {
+      value: 'file',
+      label: 'A restricted file in the Synomem home',
+      detail: 'Mode 0600. Use on headless machines with no keyring.',
+    },
+    {
+      value: 'environment',
+      label: 'Print environment-variable instructions',
+      detail: 'Nothing is stored. Synomem never edits your shell profile.',
+    },
+  ];
+}
+
+/** Refuses to guess when there is nobody to ask. */
+export function assertInteractive(io: PromptIo): void {
+  if (io.interactive) return;
+  throw new SynomemError(
+    'INVALID_INPUT',
+    [
+      'synomem config needs an interactive terminal.',
+      '',
+      'For automation, use the deterministic form instead:',
+      '',
+      '  synomem config init --backend local --yes',
+      '',
+      '  synomem config init --backend remote --auth access-key \\',
+      '    --workspace <workspace-id> --access-token-stdin --yes',
+      '',
+      'Pipe the token in rather than passing it as an argument: an argument is',
+      'kept by both the shell history and the process list.',
+    ].join('\n'),
+  );
+}
+
+/**
+ * Stores an access key in a restricted file.
+ *
+ * Separate from `config.json` so a configuration file can be read, copied or
+ * pasted into an issue without carrying a secret with it.
+ */
+export function writeCredentialFile(home: string, token: string): string {
+  const directory = join(home, 'credentials');
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  chmodSync(directory, 0o700);
+  const path = join(directory, 'installation.json');
+  writeFileSync(path, `${JSON.stringify({ accessToken: token }, null, 2)}\n`, { mode: 0o600 });
+  chmodSync(path, 0o600);
+  return path;
+}
+
+/** A key's identifying prefix. Never the key. */
+export function credentialFingerprint(token: string): string {
+  const head = token.slice(0, 12);
+  return `${head}${token.length > 12 ? '\u2026' : ''}`;
+}
+
+export function environmentInstructions(token: string): string {
+  return [
+    'Set this value for the current shell:',
+    '',
+    `  export SYNOMEM_ACCESS_TOKEN='${token}'`,
+    '',
+    'To persist it, add that to a secret-aware shell configuration or to your',
+    'agent runtime environment. Synomem will not edit your shell profile for',
+    'you: silently rewriting a dotfile is not a thing a setup program should do.',
+  ].join('\n');
+}
+
+/** The interactive flow, returning the plan it settled on. */
+export async function runConfigWizard(
+  io: PromptIo,
+  options: { home?: string; env?: NodeJS.ProcessEnv } = {},
+): Promise<ConfigPlan> {
+  assertInteractive(io);
+  const env = options.env ?? process.env;
+
+  io.output.write(
+    [
+      '',
+      'Welcome to Synomem',
+      '',
+      'Synomem gives agents durable notes, messages, tasks, todos, kudos,',
+      'and shared coordination.',
+      '',
+    ].join('\n'),
+  );
+
+  const backend = await select<BackendChoice>(io, 'Where should Synomem store canonical state?', [
+    {
+      value: 'local',
+      label: 'Local \u2014 SQLite on this machine',
+      detail: 'Nothing is uploaded. One implicit workspace.',
+    },
+    {
+      value: 'remote',
+      label: 'Synomem Cloud \u2014 shared across machines and agents',
+      detail: 'Organizations, workspaces, roles and administration.',
+    },
+  ]);
+
+  const home = await ask(io, 'Where should Synomem store its data?', resolveHome(options.home));
+
+  if (backend === 'local') {
+    return { backend, home };
+  }
+
+  const serviceUrl = cloudApiUrl(env);
+  io.output.write(`\nConnecting to Synomem Cloud at ${serviceUrl}\n`);
+
+  const auth = await select<AuthChoice>(io, 'How would you like to sign in?', [
+    {
+      value: 'browser',
+      label: 'Sign in with your browser',
+      detail: 'Opens the authorization server and returns through a loopback callback.',
+    },
+    {
+      value: 'access-key',
+      label: 'Use an installation access key',
+      detail: 'Create one at https://portal.synomem.ai/installations',
+    },
+  ]);
+
+  const workspaceId = await ask(io, 'Workspace ID');
+  if (!workspaceId) {
+    throw new SynomemError('INVALID_INPUT', 'A workspace ID is required for the hosted backend.');
+  }
+
+  const credentialStore =
+    auth === 'access-key'
+      ? await select<CredentialStoreChoice>(
+          io,
+          'Where should Synomem store this credential?',
+          credentialStoreChoices(),
+        )
+      : 'auto';
+
+  return { backend, home, serviceUrl, auth, workspaceId, credentialStore };
+}
+
+/** Reads an access key without ever accepting it as an argument. */
+export async function readAccessToken(io: PromptIo): Promise<string> {
+  const token = await askSecret(io, 'Installation access key');
+  if (!token) throw new SynomemError('INVALID_INPUT', 'No access key was provided.');
+  return token;
+}
+
+export async function confirmPlan(io: PromptIo, plan: ConfigPlan): Promise<boolean> {
+  io.output.write(
+    [
+      '',
+      'Synomem will be configured as:',
+      '',
+      `  Backend:   ${plan.backend === 'local' ? 'Local SQLite' : 'Synomem Cloud'}`,
+      `  Home:      ${plan.home}`,
+      ...(plan.serviceUrl ? [`  Service:   ${plan.serviceUrl}`] : []),
+      ...(plan.workspaceId ? [`  Workspace: ${plan.workspaceId}`] : []),
+      ...(plan.credentialStore && plan.credentialStore !== 'auto'
+        ? [`  Credential: ${plan.credentialStore}`]
+        : []),
+      '',
+    ].join('\n'),
+  );
+  return await confirm(io, 'Apply this?');
+}
+
+export function homeExists(home: string): boolean {
+  return existsSync(home);
+}

package/src/credentials.ts

@@ -6,6 +6,21 @@ import type { ActorIdentity } from './types.js';
 const serviceName = 'ai.synomem.credentials';
 const maximumOutputBytes = 128 * 1024;
 
+/**
+ * An installation access key.
+ *
+ * Not an OAuth credential: it has no refresh, no token endpoint and no client,
+ * and it authorizes a MACHINE rather than a person. Keeping it a distinct shape
+ * stops code treating it as refreshable, which would mean silently failing to
+ * renew something that never expires that way.
+ */
+export interface StoredInstallationKey {
+  kind: 'installation-key';
+  accessToken: string;
+}
+
+export type StoredCredential = StoredOAuthCredential | StoredInstallationKey;
+
 export interface StoredOAuthCredential {
   accessToken: string;
   refreshToken?: string;
@@ -17,8 +32,8 @@ export interface StoredOAuthCredential {
 }
 
 export interface CredentialStore {
-  get(reference: string): Promise<StoredOAuthCredential | undefined>;
-  set(reference: string, credential: StoredOAuthCredential): Promise<void>;
+  get(reference: string): Promise<StoredCredential | undefined>;
+  set(reference: string, credential: StoredCredential): Promise<void>;
   delete(reference: string): Promise<boolean>;
 }
 

package/src/index.ts

@@ -11,7 +11,12 @@ export {
 export { RemoteSynomemService, environmentCredentialProvider } from './remote.js';
 export type { SynomemCredentialProvider, RemoteSynomemOptions } from './remote.js';
 export { credentialReference, OsCredentialStore } from './credentials.js';
-export type { CredentialStore, StoredOAuthCredential } from './credentials.js';
+export type {
+  CredentialStore,
+  StoredCredential,
+  StoredInstallationKey,
+  StoredOAuthCredential,
+} from './credentials.js';
 export { loginWithOAuth, StoredCredentialProvider } from './oauth.js';
 export type { OAuthLoginOptions } from './oauth.js';
 export {
@@ -35,6 +40,7 @@ export type {
   ProjectionRebuildResult,
 } from './service.js';
 export { defaultConfig, resolveHome } from './config.js';
+export { cloudApiUrl, SYNOMEM_CLOUD_API_URL } from './cloud.js';
 export { asSynomemError, errorCodes, SynomemError } from './errors.js';
 export {
   dueInstant,

package/src/mcp/index.ts

@@ -6,6 +6,7 @@ import { configuredServiceFactory } from '../backend.js';
 import { SynomemError, asSynomemError } from '../errors.js';
 import {
   actorSchema,
+  agentHandleSchema,
   agentIdSchema,
   changesInputSchema,
   createNoteSchema,
@@ -88,9 +89,18 @@ export async function createSynomemMcpServer(
   options: SynomemMcpOptions,
   serviceFactory: SynomemServiceFactory = configuredServiceFactory,
 ): Promise<SynomemMcpRuntime> {
-  const actor = actorSchema.parse(options.actor);
-  const client = serviceFactory({ ...options, actor });
+  const requested = actorSchema.parse(options.actor);
+  const client = serviceFactory({ ...options, actor: requested });
   await client.init();
+  /*
+   * Every tool reports the CANONICAL actor, not the one that was asked for.
+   *
+   * A harness registers with a handle because that is what a person typed, but
+   * init resolves it against stored state — so the identity echoed back is the
+   * one the events will actually carry. Reporting the requested name would let
+   * a misconfigured runtime appear to be acting as somebody it is not.
+   */
+  const actor = client.actor;
   const server = new McpServer(
     { name: 'synomem', version: packageVersion() },
     {
@@ -282,9 +292,9 @@ export async function createSynomemMcpServer(
       description:
         'Administrative tool for creating a stable agent identity. Disabled by default so runtime agents cannot silently create identities.',
       inputSchema: z.object({
-        id: agentIdSchema,
+        handle: agentHandleSchema,
         displayName: z.string().trim().min(1).max(200),
-        aliases: z.array(agentIdSchema).max(50).optional(),
+        aliases: z.array(agentHandleSchema).max(50).optional(),
         description: z.string().trim().max(2000).optional(),
       }),
       outputSchema,
@@ -300,7 +310,11 @@ export async function createSynomemMcpServer(
           );
         }
         const profile = await client.agents.create(input);
-        return success(actor, `Created agent ${profile.displayName} (${profile.id}).`, { profile });
+        return success(
+          actor,
+          `Created agent ${profile.displayName}: handle ${profile.handle}, ID ${profile.id}.`,
+          { profile },
+        );
       } catch (error) {
         return failure(actor, error);
       }

package/src/oauth.ts

@@ -207,7 +207,14 @@ export class StoredCredentialProvider implements SynomemCredentialProvider {
   async getAccessToken(signal?: AbortSignal): Promise<string | undefined> {
     if (this.env.SYNOMEM_ACCESS_TOKEN) return this.env.SYNOMEM_ACCESS_TOKEN;
     if (!this.loaded) {
-      this.credential = await this.store.get(this.reference);
+      const stored = await this.store.get(this.reference);
+      /*
+       * An installation key is not an OAuth credential: it cannot be refreshed
+       * and has no client or token endpoint. Treating one as OAuth would mean
+       * trying to renew something that never renews that way, so this path
+       * ignores it and lets the installation-key path handle it.
+       */
+      this.credential = stored && 'kind' in stored ? undefined : stored;
       this.loaded = true;
     }
     const credential = this.credential;

package/src/projections.ts

@@ -550,7 +550,7 @@ export class ProjectionManager implements ProjectionWriter {
     const generated: string[] = [];
 
     for (const profile of profiles) {
-      const agentDirectory = join(this.storage.home, profile.id);
+      const agentDirectory = join(this.storage.home, profile.handle);
       assertNoSymlinkEscape(this.storage.home, agentDirectory);
       ensureDirectory(agentDirectory);
       const profilePath = join(agentDirectory, 'profile.json');
@@ -656,7 +656,7 @@ export class ProjectionManager implements ProjectionWriter {
       (record) => record.event.assigneeAgentId === profile.id,
     );
     const rebuiltAt = events.at(-1)?.createdAt ?? new Date(0).toISOString();
-    const agentDirectory = join(this.storage.home, profile.id);
+    const agentDirectory = join(this.storage.home, profile.handle);
     const inboxDirectory = join(agentDirectory, 'inbox');
     const kudosInboxDirectory = join(inboxDirectory, 'kudos');
     const memoInboxDirectory = join(inboxDirectory, 'memos');
@@ -729,7 +729,7 @@ export class ProjectionManager implements ProjectionWriter {
     }
 
     const keep = new Set(generated);
-    const prefixes = [`${profile.id}/`, `${profile.id}\\`];
+    const prefixes = [`${profile.handle}/`, `${profile.handle}\\`];
     const removed: string[] = [];
     for (const stale of this.storage
       .projectionManifest()
@@ -745,7 +745,7 @@ export class ProjectionManager implements ProjectionWriter {
       unlinkSync(path);
       removed.push(stale);
     }
-    this.storage.replaceAgentProjectionManifest(profile.id, generated, rebuiltAt);
+    this.storage.replaceAgentProjectionManifest(profile.handle, generated, rebuiltAt);
     return { generated: generated.sort(), removed: removed.sort() };
   }