git:20260727.68dec2e to git:20260806.65828aa

---

name: ds-identity

description: "Manage the developer identity used for session telemetry attribution."

user-invocable: true

---

# /ds-identity

Manage the developer identity used for session telemetry attribution.

Supports manual, automatic (GitHub-derived), and provisional-to-confirmed

identity flows. Identity drives per-project `.agentic/session-log/<dev>.jsonl`

and the global operator mirror at `~/.agentic/session-log/<dev>.jsonl`.

Implementation: `bin/agentic-identity` (Python 3 stdlib + optional pyyaml).

## Usage

```

```

## Subcommands

### init

```

```

Set a developer identity manually. `<handle>` must match `^[a-z0-9._-]{1,64}$`.

- `--scope global` writes `~/.agentic/identity.yml` (atomic tmp+rename).

- `--scope project` writes `<cwd>/.agentic/identity.yml` (the current repo root;

exits `1` if `cwd` is not inside a git repo). The project file is gitignored

by the existing `.agentic/*` umbrella - it is per-developer only and never

lands in the repo by default.

- If a confirmed identity already exists at the target scope, `--force` is

required to overwrite.

- If the existing identity is provisional, overwrites silently (no `--force`

needed).

- `--display-name` sets an optional human-readable name stored as

`display_name` in the target identity file.

### show

```

```

- `--scope global` (default): prints `~/.agentic/identity.yml`.

- `--scope project`: prints `<cwd>/.agentic/identity.yml`.

ordering (see "Scope / effective identity resolution" below). Also prints a

`--scope effective` is available on `show` only; it is rejected with exit `1`

on `init`, `auto`, and `confirm` (structural rejection; those subcommands write

to one explicit scope).

Example output (`--scope effective`, project identity active):

```

developer_id: repo-handle

display_name: Repo Handle

created_at: 2026-06-10T09:00:00Z

scope: project

```

Example output (provisional):

```

developer_id: jane.dev

display_name: Jane Dev

created_at: 2026-06-04T10:00:00Z

provisional: true

```

Example output (confirmed):

```

developer_id: jane.dev

display_name: Jane Dev

created_at: 2026-06-04T10:00:00Z

```

`provisional: true` appears only when the identity is provisional. Prints

"No identity set. Run: agentic-identity init <handle>" when no file exists

at the requested scope.

### auto

```

```

Derive a handle automatically from the GitHub CLI and write it as provisional.

Steps:

1. Calls `gh api user --jq .login` with a 5-second timeout.

2. Lowercases the result and validates against `^[a-z0-9._-]{1,64}$`.

Behavior on edge cases:

- `gh` unavailable or unauthenticated: exits `1` with a hint to run

`gh auth login`.

- Login fails the regex after lowercasing: exits `1` with a hint to use

`agentic-identity init <handle>`.

- A confirmed (non-provisional) identity already exists: exits `2`

(no overwrite without `--force`).

- A provisional identity already exists: overwrites silently (no `--force`

needed).

`--force` bypasses the exit-`2` guard for confirmed identities.

A provisional identity does NOT activate telemetry writes. Session data is

instead buffered at `~/.agentic/session-log/.pending/` until confirmed (see

"Provisional model" below).

### confirm

```

```

Confirm a provisional identity and activate telemetry. `--scope` defaults to

Steps:

1. Strips `provisional:` and `derived_from:` from the target identity file

(atomic tmp+rename). The identity is now confirmed.

3. Prints "Flushed N pending session(s)".

## Provisional model

When no confirmed identity exists, the Stop hook auto-derives a provisional

handle (via `auto`) and buffers session telemetry rather than writing it

to any log. This eliminates the one-session gap that existed before V1.

### Pending buffer

Location: `~/.agentic/session-log/.pending/<session-uuid>.json`

```json

{

"schema_version": 1,

"session_uuid": "<uuid>",

"ts": "<ISO8601>",

"project_slug": "<basename>",

"repo_root": "<abs cwd>",

"branch": "<branch>",

"data": {

"wall_seconds": 0,

"tokens": { "input": 0, "output": 0, "cache_creation": 0, "cache_read": 0 },

"spawn_count": 0,

"by_agent": {}

}

}

```

No `developer_id` field - sessions are unattributed until flushed.

`agentic-cost` does NOT read `.pending/` (the glob `*.jsonl` never reaches

the `.pending/` subdirectory).

### Flush (`flushPendingBuffer`)

Called by both `confirm` and `init`. Race-safe: acquires an exclusive

`fcntl.flock` on `~/.agentic/session-log/.flush.lock` for the entire flush

For each `.pending/*.json` record:

If found, unlinks the pending file and skips.

`git -C <repo_root> rev-parse --show-toplevel` (3-second timeout) and

checks that `basename(toplevel) == project_slug`. On success, appends to

`<repo_root>/.agentic/session-log/<dev>.jsonl` (mkdir -p). On mismatch or

failure, skips per-project with a one-line stderr warning.

`~/.agentic/session-log/<dev>.jsonl` (mkdir -p).

succeed. A global-write failure leaves the file for a future retry.

### First-session confirmation prompt

At the first user turn of a new session, the conductor surfaces a non-blocking

notice when a provisional identity is detected:

```

Tracking handle '<handle>' was auto-derived (provisional). Telemetry is

```

Telemetry continues to buffer (not lost). The prompt re-surfaces each session

until confirmed. CI/headless sessions never reach a user turn, so they stay

deferred and buffered automatically.

## Scope / effective identity resolution

A project-local identity file at `<repo>/.agentic/identity.yml` lets a developer

When the preflight, Stop hook, or `show --scope effective` resolves identity,

it applies this total ordering (higher tier wins):

| Tier | File | State |

|---|---|---|

| 1 (highest) | `<cwd>/.agentic/identity.yml` | confirmed (no `provisional: true`) |

Key rules:

- `--scope project` requires the `cwd` to be inside a git repo; exits `1` if not.

## Identity schema

| Field | Required | Notes |

|---|---|---|

| `developer_id` | yes | Validated handle `^[a-z0-9._-]{1,64}$` |

| `display_name` | no | Optional human-readable name |

| `created_at` | yes | ISO8601 UTC timestamp |

| `provisional` | no | Present and `true` only when auto-derived; absent means confirmed |

| `derived_from` | no | Source of the auto-derived handle; `gh` when set by `auto` |

**Back-compat:** An identity written by `agentic-identity init` before V1

has no `provisional` key. Absent `provisional` is treated as confirmed

(`provisional === false`). Existing manually-created identities need zero

migration and continue to work without change.

## Relationship to tracking

| Identity state | Telemetry destination |

|---|---|

| Confirmed | Per-project `.agentic/session-log/<dev>.jsonl` + global `~/.agentic/session-log/<dev>.jsonl` |

| Provisional | `~/.agentic/session-log/.pending/<uuid>.json` (buffered; flushed on confirm/init) |

| None | Same as provisional; Stop hook also appends an identity nudge to this session's `.agentic/context.d/` shard, which the derived `.agentic/context.md` rollup then carries |

- `agentic-cost team` reads `.agentic/session-log/` (project-local) - aggregates

all confirmed developer files for the current repo.

- `agentic-cost operator` reads `~/.agentic/session-log/*.jsonl` (global) -

cross-repo rollup for the operator across all projects.

- Pending buffer is invisible to both commands until flushed.

## Exit codes (summary)

| Code | Meaning |

|---|---|

| `0` | Success |

| `2` | A confirmed identity already exists; re-run with `--force` to overwrite |